OAI / OAI/OpenAPI-Specification

Structural improvements: enhance headers handling

Offen
#690 18 Kommentare 39 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

headers re-use: globals/defaults
Vorherrschende Sprache
Markdown
Sterne
31.2k
Forks
9.2k
Ø Merge
6 Std. 37 Min.
Gemergte PRs (30 T.)
27

Beschreibung

Following (again) ideas from OAI/OpenAPI-Specification#563 and OAI/sig-moonwalk#115, extending OAI/OpenAPI-Specification#369:

  • define reusable response headers (like parameters or definitions as proposed in OAI/OpenAPI-Specification#563 by @fehguy )
  • set responses headers on each level: whole api, path, operation, responses (and response as stated in OAI/OpenAPI-Specification#369)
paths:
  responseHeaders:
     # Headers returned on all api responses
  /resources:
    responseHeaders:
      # Headers returned on all /resources operations responses
    get:
      responseHeaders:
        # Headers returned on all operations responses
      200:
         headers:
           # Headers returned on this response
schemas:
  responseHeaders:
    # reusable headers describe with a Header Object, used with $ref

The problem is the naming consistency: responseHeaders almost everywhere vs headers on response level.
What if we use headers or responseHeaders everywhere?

nb: and don't forget to modify Header Object to include OAI/OpenAPI-Specification#321 (required)

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Prüfe die verknüpften OpenAPI Specification-Issues #563, #115, #369 und #321 und vergleiche anschließend die in diesem Issue vorgeschlagenen Platzierungen von responseHeaders und headers. Bestimme die konsistente Benennung und die Anforderungen an das Header Object, bevor du die Spezifikation änderst. Als erledigt gilt die Aufgabe, wenn der strukturelle Vorschlag und das Verhalten erforderlicher Header geklärt und konsistent dokumentiert sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
openapi
Bereich
api, backend-api-design
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

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