Swagger / OpenAPI: usa $ ref per passare un parametro definito riutilizzabile

84

Diciamo che ho un parametro come limit. Questo viene utilizzato ovunque ed è un dolore doverlo cambiare ovunque se ho bisogno di aggiornarlo:

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

Posso usare $ ref per definirlo altrove e renderlo riutilizzabile? Mi sono imbattuto in questo ticket che suggerisce che qualcuno vuole cambiare o migliorare la funzionalità, ma non posso dire se esiste già oggi o no?

swagger  swagger-2.0  openapi 
— brandonscript
fonte

Risposte:

134

Questa funzionalità esiste già in Swagger 2.0. Il ticket collegato parla di alcuni meccanismi specifici che non influiscono sulla funzionalità di questa funzione.

All'oggetto di livello superiore (indicato come oggetto Swagger), c'è una parametersproprietà in cui è possibile definire parametri riutilizzabili. È possibile assegnare qualsiasi nome al parametro e fare riferimento ad esso da percorsi / operazioni specifiche. I parametri di livello superiore sono solo definizioni e non vengono applicati automaticamente a tutte le operazioni nella specifica.

Puoi trovare un esempio qui - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - anche con un parametro limit.

Nel tuo caso, vorresti fare questo:

# 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
fonte
Puoi farlo anche con i parametri del percorso? O solo parametri di query?
— brandonscript
Qualsiasi tipo di parametro, ovunque vengano utilizzati i parametri (a livello di percorso o l'operazione stessa). La definizione del parametro di primo livello utilizza lo stesso oggetto parametro di quelli esplicitamente definiti per le operazioni.
— Ron
6
È possibile estendere un parametro? Ad esempio, la stessa definizione di parametro potrebbe essere in: pathin un caso e in: queryin un altro. Inoltre potrebbe essere opzionale in un caso e obbligatorio in un altro.
8
Dovresti creare due definizioni separate per questo.
— Ron
2
È possibile rendere riutilizzabili gli argomenti della richiesta intera? es .: parametri: $ ref: "# / parameters / requestParams"
— Konrad Gałęzowski
31

Per completezza, ecco come apparirebbe in OpenAPI (aka 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
— Milano
fonte
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.