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.