Swagger / OpenAPI: use $ ref para pasar un parámetro definido reutilizable

84

Digamos que tengo un parámetro como limit. Este se usa en todas partes y es un dolor tener que cambiarlo en todas partes si necesito actualizarlo:

parameters:
    - name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: number
      format: int32

¿Puedo usar $ ref para definir esto en otro lugar y hacerlo reutilizable? Me encontré con este ticket que sugiere que alguien quiere cambiar o mejorar la función, pero no puedo decir si ya existe hoy o no.

swagger swagger-2.0 openapi brandonscript
fuente

Respuestas:

132

Esta característica ya existe en Swagger 2.0. El ticket vinculado habla de algunas mecánicas específicas que no afectan la funcionalidad de esta función.

En el objeto de nivel superior (denominado Objeto Swagger), hay una parameterspropiedad en la que puede definir parámetros reutilizables. Puede darle al parámetro cualquier nombre y hacer referencia a él desde rutas / operaciones específicas. Los parámetros de nivel superior son solo definiciones y no se aplican a todas las operaciones en la especificación automáticamente.

Puede encontrar un ejemplo aquí: https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json , incluso con un parámetro de límite.

En su caso, querría hacer esto:

# define a path with parameter reference
/path:
   get:
      parameters:
         - $ref: "#/parameters/limitParam"
         - $ref: "#/parameters/offsetParam"

# define reusable parameters:
parameters:
   limitParam:
      name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: integer
      format: int32
   offsetParam:
      name: offset
      in: query
      description: Offset from which start returned results
      required: false
      type: integer
      format: int32
Ron
fuente
¿Puedes hacer esto también con parámetros de ruta? ¿O solo parámetros de consulta?
brandonscript
Cualquier tipo de parámetro, dondequiera que se utilicen los parámetros (a nivel de ruta o la operación en sí). La definición de parámetro de nivel superior utiliza el mismo objeto de parámetro que los definidos explícitamente para las operaciones.
Ron
6
¿Es posible ampliar un parámetro? Por ejemplo, la misma definición de parámetro podría ser in: pathen un caso y in: queryen otro. También podría ser opcional en un caso y obligatorio en otro.
8
Tendría que crear dos definiciones separadas para ello.
Ron
1
¿Es posible hacer que los argumentos de solicitud completos sean reutilizables? es decir: parámetros: $ ref: "# / parameters / requestParams"
Konrad Gałęzowski
28

Para completar, así es como se vería en OpenAPI (también conocido como swagger v3):

openapi: "3.0.0"
servers:
    - url: /v1
      description: local server

paths:
   /path:
      get:
         parameters:
            - $ref: "#/components/parameters/limitParam"

components:
   parameters:
      limitParam:
         name: limit
         in: query
         description: Limits the number of returned results
         required: false
         schema:
            type: integer
            minimum: 10
            default: 10
            multipleOf: 10 # matches 10, 20, ...
            format: int32
Milán
fuente