如何在 OpenAPI 3.0 中定义标头参数? [英] How to define header parameters in OpenAPI 3.0?

问题描述

在 OpenAPI (Swagger) 2.0 中，我们可以像这样定义标头参数:

In OpenAPI (Swagger) 2.0, we could define header parameters like so:

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

但在 OpenAPI 3.0.0 中，参数被请求体替换，我找不到定义标头参数的方法，这些参数将进一步用于身份验证.

But in OpenAPI 3.0.0, parameters are replaced by request bodies, and I cannot find a way to define header parameters, which would further be used for authentication.

在 OpenAPI 3.0.0 中定义请求标头的正确方法是什么?

What is the correct way to define request headers in OpenAPI 3.0.0?

推荐答案

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

In OpenAPI 3.0, header parameters are defined in the same way as in OpenAPI 2.0, except the type has been replaced with schema:

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

如有疑问，请查看描述参数指南.

When in doubt, check out the Describing Parameters guide.

但在 Swagger 3.0.0 中，参数被请求正文替换.

But in Swagger 3.0.0 parameters are replaced by request bodies.

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

This is only true for form and body parameters. Other parameter types (path, query, header) are still defined as parameters.

定义头参数，进一步用于身份验证.

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

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

A better way to define authentication-related parameters is to use securitySchemes rather than define these parameters explicitly in parameters. Security schemes are used for parameters such as API keys, app ID/secret, etc. In your case:

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

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

这篇关于如何在 OpenAPI 3.0 中定义标头参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！