edito - ¿Cómo definir parámetros de consulta mutuamente exclusivos en Swagger(OpenAPI)?

swagger ui

Question

Tengo una serie de parámetros en Swagger como este.

 "parameters": [
{
"name": "username",
"description": "Fetch username by username/email",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "site",
"description": "Fetch username by site",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "survey",
"description": "Fetch username by survey",
"required": false,
"type": "string",
"paramType": "query"
}
],

DEBE completarse un parámetro, pero no importa cuál, los otros se pueden dejar en blanco. ¿Hay una manera de representar esto en Swagger?

Answer 1

¿Qué hay de cambiar el diseño de su API? Actualmente tienes un método, 3 parámetros. Si entiendo bien, el usuario siempre debe proporcionar exactamente un parámetro, y los dos restantes deben estar desactivados.

Para mí, la API sería más utilizable con tres puntos finales, como

/user/byName?name=
/user/bySite?name=
/user/bySurvey?name=

Answer 2

Desafortunadamente esto no es posible en Swagger actualmente. "required" es solo un valor booleano y no hay forma de representar interdependencias entre parámetros.

Lo mejor que puede hacer es aclarar los requisitos en las descripciones de los parámetros y también colocar una descripción personalizada de 400 Solicitudes erróneas en las mismas líneas.

(Hay un poco de discusión en https://github.com/swagger-api/swagger-spec/issues/256 sobre posibles formas de implementar esto en la próxima versión de Swagger)

Answer 3

Parámetros mutuamente exclusivos son posibles (tipo de) en OpenAPI 3.0 :

• Defina los parámetros mutuamente exclusivos como propiedades de objeto y use oneOf o maxProperties para limitar el objeto a solo 1 propiedad.
• Utilice el método de serialización del parámetro style: form y explode: true , para que el objeto se ?propName=value como ?propName=value .

Un ejemplo utilizando las restricciones minProperties y maxProperties :

openapi: 3.0.0
...
paths:
/foo:
get:
parameters:
- in: query
name: filter
required: true
style: form
explode: true
schema:
type: object
properties:
username:
type: string
site:
type: string
survey:
type: string
minProperties: 1
maxProperties: 1
additionalProperties: false

Utilizando oneOf :

 parameters:
- in: query
name: filter
required: true
style: form
explode: true
schema:
type: object
oneOf:
- properties:
username:
type: string
required: [username]
additionalProperties: false
- properties:
site:
type: string
required: [site]
additionalProperties: false
- properties:
survey:
type: string
required: [survey]
additionalProperties: false

Otra versión usando oneOf :

 parameters:
- in: query
name: filter
required: true
style: form
explode: true
schema:
type: object
properties:
username:
type: string
site:
type: string
survey:
type: string
additionalProperties: false
oneOf:
- required: [username]
- required: [site]
- required: [survey]

Tenga en cuenta que Swagger UI y Swagger Editor aún no admiten los ejemplos anteriores (hasta marzo de 2018). Este problema parece cubrir la parte de representación de parámetros.

También hay una propuesta abierta en el repositorio de especificaciones OpenAPI para admitir las interdependencias entre los parámetros de consulta, por lo que quizás las futuras versiones de la Especificación tengan una mejor manera de definir tales escenarios.

Answer 4

Una alternativa es pasar un parámetro de tipo de filtro con una enumeración y un valor de filtro con el valor a usar.

Ejemplo en: https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1

Puede ser requerido o no, como usted elija. Sin embargo, si se requiere uno, ambos deben ser.