OAI / OAI/OpenAPI-Specification

Structural improvements: enhance headers handling

Abierto
#690 18 comentarios 39 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

headers re-use: globals/defaults
Lenguaje dominante
Markdown
Estrellas
31.2k
Forks
9.2k
Merge medio
6 h 37 min
PR fusionados (30 d)
27

Descripción

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)

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Línea de trabajo

Revisa las incidencias vinculadas de OpenAPI Specification #563, #115, #369 y #321 y, a continuación, compara las ubicaciones propuestas de responseHeaders y headers en esta incidencia. Determina la nomenclatura coherente y los requisitos de Header Object antes de modificar la especificación. Se considera completado cuando la propuesta estructural y el comportamiento de los headers requeridos estén resueltos y documentados de forma coherente.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
openapi
Área
api, backend-api-design
Tipo de issue
Nueva funcionalidad
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
25/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.