swagger - 如何在Swagger中指定GET参数的示例？

Question

我正在使用在线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 标记，我会收到一条错误消息:

is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>

在Swagger中写入GET参数时如何设置示例？

Answer 1

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.x

OpenAPI 3.x 支持参数示例:

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