如何在 OpenAPI 3.0 中定义 header 参数？

Question

在 OpenAPI (Swagger) 2.0 中，我们可以这样定义 header 参数：

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

但是在 OpenAPI 3.0.0 中，参数被请求主体取代，我找不到定义 header 参数的方法，这些参数将进一步用于身份验证。

在 OpenAPI 3.0.0 中定义请求 header 的正确方法是什么？

Answer 1

在 OpenAPI 3.0 中，header 参数的定义方式与 OpenAPI 2.0 中的相同，只是 type 已替换为 schema:

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

如有疑问，请查看 Describing Parameters 指南。

But in Swagger 3.0.0 parameters are replaced by request bodies.

这仅适用于表单和 body 参数。其他参数类型（路径、查询、header）仍然定义为parameters.

define header parameters, which would further be used for authentication.

定义 authentication-related 参数的更好方法是使用 securitySchemes 而不是在 parameters 中显式定义这些参数。安全方案用于 API 密钥、应用程序 ID/secret 等参数。在您的情况下：

components:
  securitySchemes:
    usernameHeader:
      type: apiKey
      in: header
      name: X-Username

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

如何在 OpenAPI 3.0 中定义 header 参数？

How to define header parameters in OpenAPI 3.0?

swagger

openapi