Как определить параметры заголовка в OpenAPI 3.0?

В OpenAPI (Swagger) 2.0 мы могли бы определить параметры заголовка следующим образом: 

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username

Но в OpenAPI 3.0.0 параметры заменяются телами запросов, и я не могу найти способ определить параметры заголовка, которые в дальнейшем будут использоваться для аутентификации.

Как правильно определить заголовки запросов в OpenAPI 3.0.0?

1 3
openapi

1 ответ:

В OpenAPI 3.0 параметры заголовка определяются так же, как и в OpenAPI 2.0, за исключением того, что type был заменен на schema: 

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username
          schema:
            type: string

Если вы сомневаетесь, проверьте руководство , описывающее параметры.

Но в Swagger 3.0.0 параметры заменяются телами запросов.

Это справедливо только для параметров формы и тела. Другие типы параметров (путь, запрос, заголовок) по-прежнему определяются как parameters.

Определите параметры заголовка, которые в дальнейшем будет использоваться для аутентификации.

Лучший способ определить параметры, связанные с аутентификацией, - использовать securitySchemes, а не определять эти параметры явно в parameters. Схемы безопасности используются для таких параметров, как ключи API, идентификатор приложения/секрет и т. д. В вашем случае: 
components:
  securitySchemes:
    usernameHeader:
      type: apiKey
      in: header
      name: X-Username

paths:
  /post:
    post:
      security:
        - usernameHeader: []
      ...
5