Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

Enhance Response cache-control header

Offen
  • Stimmt etwas nicht?
#2,784 5 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
25/100
Issue-Typ
Feature
Klarheit
Muss geklärt werden
Aktivitätsstatus
Veraltet
Bereich
api, documentation

Rechercherichtung

Beginnen Sie mit der Prüfung von OpenAPI Header Object, der JSON-Schema-Unterstützung und den Cache-Control-Beispielen in diesem Issue. Es sind keine Repository-Dateien oder Tests angegeben; für die Fertigstellung müsste man sich auf eine präzise, interoperable Art einigen und diese dokumentieren, um durch Kommas getrennte Direktiven und Schlüssel-Wert-Direktiven wie max-age darzustellen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

headers http param serialization

I have been trying to use Open API to specify the expected Cache rules for some API routes

While defining such rules through the Expires and/or Pragma headers can be quite simple (a date for Expires & the no-cache constant for Pragma), they are not the modern way to do it. Pragma is deprecated, and Expires is ignored when Cache-Control is defined.

Cache-Control is also nowadays supported by all clients making it the most obvious solution to define the caching rules.

Unfortunately, the current OPEN API Header Object support looks a bit limited for Cache-Control. Using pure JSON Schema definition might produce unexpected behavior without dedicated context for this header or for headers having similar Design.

This header value is defined as a comma-seperated list of properties called directives
If all directives were simple strings I could write something like that if I allowed any of them (or restrict to the on I accept by design)

      responses:
        200:
          description: "The request was successfully treated."
          headers:
            Cache-Control: 
              schema:
                type: array
                items:
                  type: string
                  enum:
                  - public
                  - private
                  - no-cache
                  - no-store
                  - must-revalidate
                  - proxy-revalidate
                  - immutable
                  - no-transform
                  - only-if-cached

If I want my route to prevent response to be cached I can easily design it a more simple way

            Cache-Control: 
              schema:
                type: string
                enum:
                - no-store

Or with the last JSON-Schema edition support of constants

            Cache-Control: 
              schema:
                const: "no-store"

But some of the most important cache control properties are key value pairs like max-age=300

I tried to express it the most reiable still simple way using adavanced JSON Schema feature unfortunately not really well supported (yet?) by Open API implementations

Sample 1

  • Pro:
    • shortest
  • Cons:
    • forbid different property order
    • forbid potentially acceptable other cache-control properties
    • not really the most inspectable
            Cache-Control: 
              schema:
                const: "public, max-age=300"

Sample 2

  • Pro:
    • still short
  • Cons:
    • ⚠️❌ the specification doesn't say how to serialize the object
            Cache-Control: 
              schema:
                const: ["public", {"max-age": 300}]

Sample 3

  • Pro:
    • explicit, no need for const support
  • Cons:
    • very verbose
    • pretty sure enum not well supported for numbers
    • ⚠️❌ the specification still doesn't say how to serialize the object
            Cache-Control: 
              schema:
                type: array
                items:
                  allOf:
                  - type: string
                    enum:
                    - public
                  - type: object
                    properties:
                      max-age:
                        type: number
                        enum:
                        - 300
                      required:
                      - max-age
Vorherrschende Sprache
Markdown
Sterne
31.2k
Forks
9.2k
Ø Merge
2 T. 9 Std.
Gemergte PRs (30 T.)
17

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus OAI/OpenAPI-Specification

Alle Issues in OAI/OpenAPI-Specification

Ähnliche Issues

Weitere Issues zu Backend & API Design

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.