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

swagger type email

Question

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.

Answer 1

Esta característica ya existe en Swagger 2.0. El ticket vinculado habla de algunos mecanismos específicos que no afectan la funcionalidad de esta función.

En el objeto de nivel superior (denominado Swagger Object), hay una propiedad de parameters donde puede definir parámetros reutilizables. Puede darle cualquier nombre al parámetro y consultarlo 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 de forma automática.

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 tu caso, querrías hacer esto:

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

# define reusable parameters:
parameters:
   limitParam:
      name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: integer
      format: int32