swagger - 如何在 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 中，头参数的定义方式与 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.

这仅适用于表单和正文参数。其他参数类型(路径、查询、标题)仍定义为 parameters .

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

定义身份验证相关参数的更好方法是使用 securitySchemes而不是在 parameters 中明确定义这些参数.安全方案用于 API key 、应用程序 ID/ secret 等参数。在您的情况下:

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

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