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.