web-dev-qa-db-ja.com

クエリまたは本文、あるいはその両方のSwaggerパラメータ

私たちのAPIには、queryとbodyの両方のパラメーターを同時にサポートするエンドポイントがあり、これらの2つのパラメーターセットをマージします。

例えば：

/foo?param1=value1
body: {
    param2=value2
}

結果のパラメータセットには、param1とparam2の2つが含まれます。

このエンドポイントは次のように使用できます。

/foo?param1=value1&param2=value2

OR

/foo
body: {
    param1=value1,
    param2=value2
}

Swaggerでこの「二重性」を指定する方法はありますか？

[〜＃〜]更新[〜＃〜]
パラメータを両方として定義する必要があると思います：bodyとquery

in:
  - body
  - query
swaggerswagger-codegen
7
igr

クエリパラメータと本文パラメータの両方を定義する必要がありますが、それらすべてをオプションとしてマークします。操作descriptionを使用して、クライアントがパラメーターをクエリ文字列または本文で送信できることを説明します。

swagger: '2.0'
...
paths:
  /foo:
    post:
      consumes:
        - application/json
      parameters:
        - in: query
          name: param1
          type: string
          required: false
        - in: query
          name: param2
          type: string
          required: false
        - in: body
          name: body
          required: false
          schema:
            type: object
            properties:
              param1:
                type: string
              param2:
                type: string

OpenAPI 3.0を使用すると、クエリ文字列とリクエスト本文に同じschemaを再利用できるという点で、少し洗練されています。

openapi: 3.0.0
...
paths:
  /foo:
    post:
      parameters:
        # This expands into ?param1=value1&param2=value2&...
        - in: query
          name: parameters
          required: false
          schema:
            $ref: '#/components/schemas/Parameters'
          style: form
          explode: true
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Parameters'
      responses:
        '200':
          description: OK

components:
  schemas:
    Parameters:
      type: object
      properties:
        param1:
          type: string
        param2:
          type: string

Swagger UIユーザーへの注意：オブジェクトのクエリ文字列へのシリアル化は、UI v。3.11.0ではまだサポートされていないようです。

6
Helen