OAI / OAI/OpenAPI-Specification
Structural improvements: enhance headers handling
Dieses Issue hat noch niemand übernommen.
- 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
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Ö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