如何在Swagger文档中表示内部服务器的额外请求头参数？

嘿，这个问题我太熟了！要在Swagger里定义所有请求都必须携带的通用请求头参数，有两种高效的方式，既能避免重复写参数，还能保证所有接口的一致性：

1. Swagger 2.0 版本：全局参数定义 #

如果你的API还在用Swagger 2.0规范，可以直接在根节点下定义parameters，然后在每个接口里通过$ref引用这些参数：

swagger: '2.0'
info:
  title: 内部服务器API
  version: 1.0.0

# 全局通用请求头参数集合
parameters:
  device_id:
    name: device_id
    in: header
    required: false
    type: string
  ip_address:
    name: ip_address
    in: header
    required: true
    type: string
  client_id:
    name: client_id
    in: header
    required: true
    type: string
  request_id:
    name: request_id
    in: header
    required: true
    type: string

paths:
  /api/user/profile:
    get:
      # 引用全局定义的请求头参数
      parameters:
        - $ref: '#/parameters/device_id'
        - $ref: '#/parameters/ip_address'
        - $ref: '#/parameters/client_id'
        - $ref: '#/parameters/request_id'
      responses:
        200:
          description: 获取用户信息成功

2. OpenAPI 3.x 版本：组件复用（推荐） #

如果用的是更现代的OpenAPI 3.x规范，推荐用components来统一管理这些通用参数，这种方式更清晰，扩展性也更强。而且你还可以把这些参数直接绑定到所有路径上，不用每个接口单独引用：

openapi: 3.0.3
info:
  title: 内部服务器API
  version: 1.0.0

components:
  parameters:
    DeviceId:
      name: device_id
      in: header
      required: false
      schema:
        type: string
    IpAddress:
      name: ip_address
      in: header
      required: true
      schema:
        type: string
    ClientId:
      name: client_id
      in: header
      required: true
      schema:
        type: string
    RequestId:
      name: request_id
      in: header
      required: true
      schema:
        type: string

paths:
  # 全局绑定：所有路径自动继承这些请求头参数
  parameters:
    - $ref: '#/components/parameters/DeviceId'
    - $ref: '#/components/parameters/IpAddress'
    - $ref: '#/components/parameters/ClientId'
    - $ref: '#/components/parameters/RequestId'

  /api/user/profile:
    get:
      responses:
        '200':
          description: 获取用户信息成功
  /api/orders/create:
    post:
      responses:
        '201':
          description: 订单创建成功

额外提示 #

• 定义完成后，Swagger UI会自动在每个请求的头部分展示这些参数，必填参数会标注*，方便测试时填写。
• 虽然文档里定义了必填项，但实际服务器的校验逻辑还是要自己实现，Swagger只是做文档和前端提示用的哦。

内容的提问来源于stack exchange，提问作者Andrew Emery