web-dev-qa-db-ja.com

SwaggerでGETパラメーターの例を指定するにはどうすればよいですか?

オンラインの Swagger Editor を使用して、APIのSwagger仕様を作成しています。

私のAPIには単一のGETリクエストエンドポイントがあり、次のYAMLコードを使用して入力パラメーターを記述しています。

paths:
  /fooBar:
    get:
      tags:
        - foobar
      summary: ''
      description: ''
      operationId: foobar
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          type: string
          example: 123, FakeStreet
        - name: city
          in: query
          description: City of the Address
          required: true
          type: string
          example: New York

exampleタグを挿入すると、次のエラーが表示されます。

<#/ definitions/parameter>、<#/ definitions/jsonReference>の1つではありません

SwaggerでGETパラメーターを記述するときに例を設定するにはどうすればよいですか?

15

OpenAPI 2.0

OpenAPI/Swagger 2.0には、非本体パラメーター用のexampleキーワードがありません。パラメーターdescriptionで例を指定できます。 Swagger UI v2、v3.12 +、Dreddなどの一部のツールもx-exampleこの目的の拡張プロパティ:

      parameters:
        - name: address
          in: query
          description: Address to be foobared. Example: `123, FakeStreet`.  # <-----
          required: true
          type: string
          x-example: 123, FakeStreet   # <-----

OpenAPI 3.0

パラメーターの例は、OpenAPI 3.0でネイティブにサポートされています。

      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          schema:
            type: string
            example: 123, FakeStreet   # <----
          example: 456, AnotherStreet  # Overrides schema-level example
25
Helen