tools - Swagger 2.0: ¿cómo hacer que "uno u otro" parámetro requerido?

swagger web

Question

Tengo un recurso de swagger 2.0 definido a continuación. ¿Cómo puedo hacer "param1 o param2" requerido? La persona que llama tiene que pasar param1 o param2.

/some/res:
put:
summary: some resource
responses:
200:
description: Successful response
schema:
$ref: ''#/definitions/SomeResponse''
parameters:
- name: param1
type: string
description: param1
in: formData
required: false
- name: param2
type: string
description: param2
in: formData
required: false

Answer 1

El escenario específico en esta pregunta, una solicitud POST / PUT / PATCH con un cuerpo de datos de formulario que contiene param1 o param2 , se puede definir utilizando OpenAPI 3.0 y oneOf :

openapi: 3.0.0
...
paths:
/some/res:
put:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- type: object
properties:
param1:
type: string
required:
- param1
additionalProperties: false
- type: object
properties:
param2:
type: string
required:
- param2
additionalProperties: false

Nota para los usuarios de Swagger UI: la IU de datos de formulario y la representación de ejemplo para los esquemas oneOf no están disponibles para las definiciones de OpenAPI 3.0.

Answer 2

En la sección Dependencias de parámetros de los documentos de Describing Parameters Swagger:

Swagger no admite dependencias de parámetros y parámetros mutuamente exclusivos. Hay una solicitud de función abierta en https://github.com/OAI/OpenAPI-Specification/issues/256 .

A partir de junio de 2017, ese problema tenía 21 votos a la baja, lo que lo convierte en el tercer tema más votado en el proyecto.

Answer 3

La especificación OpenAPI (fka Swagger) no admite parámetros condicionales o mutuamente exclusivos (de ningún tipo).

Hay una solicitud de función abierta:
Apoyar las interdependencias entre los parámetros de consulta

Answer 4

La especificación Swagger no admite el requisito condicional o la inclusión / exclusión de parámetros.

Lo que sugeriría es indicar claramente en la descripción sus reglas para la inclusión / exclusión de parámetros de consulta. Luego, utilizando un marco de validación, que depende de su idioma (es decir, javax.validation para Java, restify-validation para restify, etc.), valide los parámetros en consecuencia.