Как указать примеры для параметров GET в Swagger?

Я использую интерактивный редактор Swagger, чтобы создать спецификацию Swagger для моего API.

В моем 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>

Как мне показать пример при записи параметров GET в Swagger?


openapi swagger swagger-2.0 swagger-editor
person Devdatta Tengshe    schedule 12.05.2017    source источник

Ответы (1)


arrow_upward
31
arrow_downward

OpenAPI 2.0

OpenAPI / Swagger 2.0 не имеет ключевого слова example для параметров, не являющихся основными. Вы можете указать примеры в параметре description. Некоторые инструменты, такие как Swagger UI v2, v3.12 + и Dredd, также поддерживают для этой цели свойство extension 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
person Helen    schedule 12.05.2017