web-dev-qa-db-ja.com

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

limitのようなパラメーターがあるとします。これはあちこちで使用されており、更新する必要がある場合はどこでも変更しなければならないのは苦痛です：

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

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

swaggerswagger-2.0openapi
69
brandonscript

この機能はSwagger 2.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
119
Ron

完全を期すために、ここでは 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
10
milan

このようにmultipleパラメーターのセットもリンクできますか？つまり.

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

Paramsがmultipleパラメータ、たとえばlimit、offset、lastModifiedAfterを定義している場合... one単一パラメータが定義されている場合のみ、動作しません。

0
girgen