Swagger / OpenAPI - Verwenden Sie $ ref, um einen wiederverwendbaren definierten Parameter zu übergeben

84

Angenommen, ich habe einen Parameter wie limit. Dieser wird überall verwendet und es ist ein Schmerz, ihn überall ändern zu müssen, wenn ich ihn aktualisieren muss:

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

Kann ich $ ref verwenden, um dies an anderer Stelle zu definieren und wiederverwendbar zu machen? Ich bin auf dieses Ticket gestoßen, das darauf hindeutet, dass jemand die Funktion ändern oder verbessern möchte, aber ich kann nicht sagen, ob sie heute bereits existiert oder nicht.

swagger swagger-2.0 openapi Brandonscript
quelle

Antworten:

132

Diese Funktion ist bereits in Swagger 2.0 vorhanden. Das verknüpfte Ticket beschreibt einige spezifische Mechanismen, die die Funktionalität dieser Funktion nicht beeinträchtigen.

Auf dem Objekt der obersten Ebene (als Swagger-Objekt bezeichnet) gibt es eine parametersEigenschaft, in der Sie wiederverwendbare Parameter definieren können. Sie können dem Parameter einen beliebigen Namen geben und aus Pfaden / bestimmten Operationen darauf verweisen. Die Parameter der obersten Ebene sind nur Definitionen und werden nicht automatisch auf alle Operationen in der Spezifikation angewendet.

Ein Beispiel dafür finden Sie hier - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - auch mit einem Grenzwertparameter.

In Ihrem Fall möchten Sie Folgendes tun:

# 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
quelle
Können Sie dies auch mit Pfadparametern tun? Oder nur Abfrageparameter?
Brandonscript
Jeder Parametertyp, unabhängig davon, wo Parameter verwendet werden (auf Pfadebene oder bei der Operation selbst). Die Parameterdefinition der obersten Ebene verwendet dasselbe Parameterobjekt wie diejenigen, die explizit für Operationen definiert wurden.
Ron
6
Ist es möglich, einen Parameter zu erweitern? Beispielsweise könnte dieselbe Parameterdefinition in: pathin einem Fall und in: queryin einem anderen sein. Kann in einem Fall auch optional sein und in einem anderen erforderlich sein.
8
Sie müssten zwei separate Definitionen dafür erstellen.
Ron
1
Ist es möglich, ganze Anforderungsargumente wiederverwendbar zu machen? dh: Parameter: $ ref: "# / parameters / requestParams"
Konrad Gałęzowski
27

Der Vollständigkeit halber sieht es in OpenAPI (auch bekannt als swagger v3) folgendermaßen aus:

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
Mailand
quelle