web-services - tools - swagger tutorial

Cómo definir un parámetro opcional en la ruta usando swagger

Question

Hay una función en mi servicio web REST que funciona con el método GET y tiene dos parámetros opcionales.

Intenté definirlo en Swagger, pero me encontré con un error, no con una definición de parámetro válida , después de configurar el required como false .

Descubrí que si establezco el valor required como true el error desaparecerá. Aquí hay una muestra de mi código de Swagger.

...
paths:
  ''/get/{param1}/{param2}'':
    get:
      ...
      parameters:
      - name: param1
        in: path
        description: ''description regarding param1''
        required: false
        type: string
      - name: param2
        in: path
        description: ''description regarding param2''
        required: false
        type: string

No experimenté esto con parámetros en el cuerpo o los que están en consulta. Creo que este problema solo está relacionado con los parámetros en la ruta. No pude encontrar ninguna solución en los archivos de especificación Swagger tampoco.

¿Hay alguna otra manera de definir parámetros opcionales en Swagger o tengo algún error en mi código?

Cualquier ayuda sería apreciada.

Answer 1

Dado que el parámetro de ruta debe ser requerido de acuerdo con la especificación OpenAPI / Swagger , puede considerar agregar 2 puntos finales separados con las siguientes rutas:

• /get/{param1}/{param2} cuando se proporciona param2
• /get/{param1}/ cuando no se proporciona param2

Answer 2

Es probable que explote porque no puede tener un parámetro uri base opcional, solo valores de cadena de consulta (en el caso de una url).

Por ejemplo:

• GET / products / {id} / pricing? Foo = bar
• ** Si foo es opcional, entonces su parámetro IN debe ser "consulta" no "ruta"
• ** Si {id} es opcional, entonces algo está mal. {id} no puede ser opcional porque está contenido dentro de la base uri.

Esto debería funcionar:

{
"in":"query",
"required":false
}

Esto no debería funcionar

{
"in":"path",
"required":false
}

cambie su propiedad "in" para que sea "query" en lugar de "path" y debería funcionar.

Answer 3

Su YAML falla porque como se indica en la especificación:

Determina si este parámetro es obligatorio. Si el parámetro está en "ruta", esta propiedad es obligatoria y su valor DEBE ser verdadero.

Fuente: http://swagger.io/specification/#parameterObject (mira en la tabla de campos fijos )