web-dev-qa-db-fra.com

Swagger / OpenAPI - utilisez $ ref pour passer un paramètre défini réutilisable

Disons que j'ai un paramètre comme limit. Celui-ci s'utilise partout et c'est pénible de devoir le changer partout si j'ai besoin de le mettre à jour:

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

Puis-je utiliser $ ref pour définir cela ailleurs et le rendre réutilisable? Je suis tombé sur ce ticket qui suggère que quelqu'un veut changer ou améliorer une fonctionnalité, mais je ne peux pas dire si elle existe déjà aujourd'hui ou non?

swaggerswagger-2.0openapi
69
brandonscript

Cette fonctionnalité existe déjà dans Swagger 2.0. Le ticket lié parle de certains mécanismes spécifiques qui n’affectent pas les fonctionnalités de cette fonctionnalité.

Au niveau de l’objet de niveau supérieur (appelé objet Swagger), il existe une propriété parameters dans laquelle vous pouvez définir des paramètres réutilisables. Vous pouvez attribuer n'importe quel nom au paramètre et y faire référence à partir de chemins/opérations spécifiques. Les paramètres de niveau supérieur ne sont que des définitions et ne sont pas appliqués automatiquement à toutes les opérations de la spécification.

Vous trouverez un exemple ici - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - même avec un paramètre limite.

Dans votre cas, vous voudriez faire ceci:

# 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
119
Ron

Pour être complet, voici à quoi cela ressemblerait dans OpenAPI (a.k.a 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
10
milan

Pouvez-vous lier également un ensemble de multiples paramètres? C'est à dire.

paths:
  /path:
    get:
      parameters:
        - $ref: "#/components/parameters/params"
components:
  parameters:
    params:
      - name: foo
        schema:
          type: string
      - name: bar
        schema:
          type: integer

Où paramètres définissent plusieurs paramètres, par exemple, limite, décalage, lastModifiedAfter ... Je ne peux pas que cela fonctionne, uniquement avec n unique paameter défini.

0
girgen