如何在OpenAPI 3.0中定义用于认证的请求头参数？

别担心，OpenAPI 3.0.0并没有取消请求头参数的定义——你可能只是混淆了请求体（requestBody）和参数的位置而已！3.0版本只是把原来放在parameters里的请求体参数移到了独立的requestBody字段，但请求头、路径、查询、Cookie参数依然在parameters数组中定义，和2.0的逻辑是一致的。

一、普通请求头参数的定义方式 #

如果你只是需要给某个接口单独定义请求头参数（比如X-username），直接在接口的parameters数组里声明即可，和2.0的写法非常相似，只是3.0要求补充schema字段来指定参数类型：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0
paths:
  /post:
    post:
      summary: 提交数据
      parameters:
        - in: header
          name: X-username
          required: true  # 根据需求设置是否必填
          schema:
            type: string
          description: 用户认证用的用户名请求头
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
      responses:
        '200':
          description: 请求成功

二、用于认证的请求头：推荐使用Security Schemes #

既然你提到这个请求头是用于认证的，OpenAPI 3.0更推荐用**安全方案（Security Schemes）**来统一定义，这样可以全局复用，也更符合API规范。具体步骤如下：

1. 在components/securitySchemes里定义认证类型为apiKey的方案，指定位置为header，参数名是X-username
2. 在接口级别或全局的security字段中引用这个方案

示例代码：

openapi: 3.0.0
info:
  title: 带认证的示例API
  version: 1.0.0
components:
  securitySchemes:
    UsernameHeaderAuth:  # 自定义的安全方案名称
      type: apiKey
      in: header
      name: X-username
      description: 通过请求头X-username传递用户名进行认证
paths:
  /post:
    post:
      summary: 需要认证的提交接口
      security:
        - UsernameHeaderAuth: []  # 引用上面定义的安全方案
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
      responses:
        '200':
          description: 请求成功
        '401':
          description: 未提供X-username认证头

这种方式的好处是：如果多个接口都需要这个认证头，只需在security里引用即可，无需重复定义；同时，Swagger UI等工具会自动识别这个认证方案，展示对应的认证输入框，提升API文档的易用性。

总结一下：OpenAPI 3.0只是重构了请求体的定义，请求头参数的定义逻辑和2.0基本一致，而用于认证的请求头更推荐用安全方案来统一管理。

内容的提问来源于stack exchange，提问作者kritika agarwal