Как определить пользовательские заголовки в OpenAPI 2.0 (Swagger 2.0)? - PullRequest
Новая
       16

Как определить пользовательские заголовки в OpenAPI 2.0 (Swagger 2.0)?

1 голос
/ 18 апреля 2019

У меня проблемы с определением пользовательских заголовков запросов для моего документа OpenAPI (Swagger).Я посмотрел в документации https://swagger.io/docs/specification/describing-parameters/#header-parameters, но не могу заставить его работать.

В моем примере ниже приведен запрос POST, имеющий тело.Я также хочу, чтобы он имел собственный заголовок, такой как мой второй фрагмент, но он недействителен.

Это нормально: 

 /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Array of Domain Names
          required: true
          schema:
            $ref: '#/definitions/DomainNames'

Это не правильно: 

  /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
       - in: header
          name: X-Request-ID
          schema:
            type: string
            format: uuid
          required: true
        - in: body
          name: body
          description: Array of Domain Names
          required: true
          schema:
            $ref: '#/definitions/DomainNames'

В строке - in: header появляется следующая ошибка:

Ошибка схемы в путях ['/ search']. Post.parameters [0] .in
должна быть равнаодно из допустимых значений
allowValues: тело, заголовок, formData, запрос, путь
Перейти к строке 37

Ошибка схемы на путях ['/ search']. post.parameters [0]
НЕ ДОЛЖНО иметь дополнительные свойства
extraProperty: схема, имя, имя
Перейти к строке 37

Что мне здесь не хватает?Заголовок отображается в визуализированном интерфейсе Swagger, но я не могу «сохранить» его, так как он недействителен.

1 Ответ

0 голосов
/ 18 апреля 2019

Руководство, на которое вы ссылаетесь, относится к OpenAPI 3.0 (как указано в верхней части этой страницы).Соответствующее руководство по OpenAPI 2.0 находится здесь: Описание параметров .

В OpenAPI 2.0 параметры пути / заголовка / запроса / формы не используют schema, они используют ключевое слово type напрямую.

Кроме того, строка - in: header в вашем примере имеет недостаточно отступ, вам нужно добавить еще один пробел, чтобы выровнять ее с другими строками.

Вот правильная версия: 

      parameters:
        - in: header     # <----
          name: X-Request-ID
          type: string   # <----
          format: uuid   # <----
          required: true
...