swagger - Pavonearse; Especifique dos respuestas con el mismo código basado en el parámetro opcional.

swagger-2.0

Question

Esta pregunta no es un duplicado de ( Swagger - Especificar propiedad de objeto opcional o respuestas múltiples ) porque ese OP estaba intentando devolver un 200 o un 400.

Tengo un GET con un parámetro opcional; Por ejemplo, GET /endpoint?selector=foo .

Quiero devolver un 200 cuyo esquema es diferente según si se pasó el parámetro, por ejemplo:

GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah -> {200, schema_2}

En el yaml, intenté tener dos códigos 200, pero el espectador los aplasta como si solo especificara uno.

¿Hay alguna forma de hacer esto?

Edición: lo siguiente parece relacionado: https://github.com/OAI/OpenAPI-Specification/issues/270

Answer 1

OpenAPI 3.0 le permite usar oneOf para definir múltiples cuerpos de solicitud o de respuesta posibles para la misma operación:

openapi: 3.0.0
...
paths:
/path:
get:
responses:
''200'':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: ''#/components/schemas/ResponseOne''
- $ref: ''#/components/schemas/ResponseTwo''

Sin embargo, no es posible asignar respuestas específicas a valores de parámetros específicos. Tendrá que documentar estos detalles verbalmente en la description .

Nota para los usuarios de Swagger UI: A partir de este escrito (diciembre de 2018), Swagger UI no genera automáticamente ejemplos para los esquemas oneOf y anyOf . Puedes seguir este tema para actualizaciones.

Como solución alternativa, puede especificar un example respuesta manualmente. Use un solo example , no múltiples examples (la compatibilidad con múltiples ejemplos tampoco está disponible todavía en la interfaz de usuario de Swagger).

 responses:
''200'':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: ''#/components/schemas/ResponseOne''
- $ref: ''#/components/schemas/ResponseTwo''
example: # <--------
foo: bar

Answer 2

Quería lo mismo, y se me ocurrió una solución que parece funcionar:

Acabo de definir dos caminos diferentes:

/path:
(...)
responses:
200:
description: Sucesso
schema:
$ref: ''#/definitions/ResponseOne''
(...)
/path?parameter=value:
(...)
responses:
200:
description: Sucesso
schema:
$ref: ''#/definitions/ResponseTwo''
(...)

Los caminos funcionan en el editor swagger. Incluso puedo documentar cada opción de manera diferente y poner parámetros opcionales que solo pueden estar en el segundo caso juntos, lo que hace que el documento API sea mucho más limpio. Usando operationId puede generar nombres más limpios para los métodos API generados.

He publicado la misma solución aquí ( https://github.com/OAI/OpenAPI-Specification/issues/270 ) para verificar si me falta algo más.

Entiendo que no está explícitamente permitido / alentado a hacerlo (tampoco encontré un lugar que lo rechace explícitamente). Pero como solución alternativa, y ser la única forma de documentar una API con este comportamiento en la especificación actual, parece una opción.

Dos problemas que he descubierto con él:

• La URL de gen de código Java escapa del signo "=", por lo tanto no funcionará a menos que corrijas esto en el código generado. Probablemente suceda en otros generadores de código.
• Si tiene más parámetros de consulta, agregará un extra "?" y fallan;

Si esos no son bloqueadores, al menos le permitirá documentar adecuadamente estos casos y permitir las pruebas con el editor swagger.