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

Solución:

Los parámetros mutuamente excluyentes son posibles (más o menos) en OpenAPI 3.0:

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

Un ejemplo usando el minProperties y maxProperties restricciones:

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 son compatibles con los ejemplos anteriores (a partir de 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 la Especificación de OpenAPI para admitir las interdependencias entre los parámetros de consulta, por lo que tal vez las versiones futuras de la Especificación tengan una mejor manera de definir tales escenarios.

Desafortunadamente, esto no es posible actualmente. “required” es solo un 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 incluir una descripción personalizada de 400 Bad Request en la misma línea.

Hay un poco de discusión en https://github.com/OAI/OpenAPI-Specification/issues/256 sobre posibles formas de implementar esto en la próxima versión de la especificación OpenAPI.

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

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

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

---

---

Utiliza Nuestro Buscador