Swagger / OpenAPI- $ refを使用して、再利用可能な定義済みパラメーターを渡します


84

のようなパラメータがあるとしましょうlimit。これはあちこちで使用されており、更新する必要がある場合はどこでも変更する必要があるのは面倒です。

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

$ refを使用してこれを他の場所で定義し、再利用可能にすることはできますか?誰かが機能を変更または改善したいと示唆しているこのチケットに出くわしましたが、それが今日すでに存在するかどうかわかりませんか?

回答:


132

この機能はSwagger2.0にすでに存在します。リンクされたチケットは、この機能の機能に影響を与えない、その特定のメカニズムについて説明しています。

最上位のオブジェクト(Swaggerオブジェクトと呼ばれる)には、parameters再利用可能なパラメーターを定義できるプロパティがあります。パラメータには任意の名前を付けて、パス/特定の操作から参照できます。トップレベルのパラメータは単なる定義であり、仕様のすべての操作に自動的に適用されるわけではありません。

ここでその例を見つけることができます--https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json-制限パラメーターがあっても。

あなたの場合、あなたはこれをしたいと思うでしょう:

# 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

パスパラメータでもこれを行うことができますか?またはクエリパラメータのみ?
brandonscript 2014年

パラメータが使用される場所(パスレベルまたは操作自体)に関係なく、任意のパラメータタイプ。最上位のパラメーター定義は、操作用に明示的に定義されたものと同じパラメーターオブジェクトを使用します。
ロン

6
パラメータを拡張することは可能ですか?たとえば、同じパラメータ定義があるin: path場合とin: query別の場合があります。また、ある場合にはオプションであり、別の場合には必須である可能性があります。

8
そのために2つの別々の定義を作成する必要があります。
ロン

1
リクエスト引数全体を再利用可能にすることは可能ですか?すなわち:パラメータ:$ REF: "#/パラメータ/ requestParams"
コンラッド・Gałęzowski

28

完全を期すために、OpenAPI(別名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
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.