在OpenAPI 3.0.0 YAML文件中能否复用公共请求头定义？

当然可以，OpenAPI 3.0.0 提供了组件复用机制，能彻底解决你现在重复定义请求头的冗余问题。下面给你两种实用方案：

方案一：全局生效（所有接口自动继承） #

如果所有接口都需要这组公共请求头，直接在全局配置里定义，不用每个接口单独加：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0

# 第一步：在components里定义公共请求头模板
components:
  parameters:
    AuthorizationHeader:
      in: header
      name: Authorization
      schema:
        type: string
      required: true
    ConsumerKeyHeader:
      in: header
      name: Consumer-Key
      schema:
        type: string
      required: true
    CorrelationIdHeader:
      in: header
      name: Correlation-Id
      schema:
        type: string
        format: uuid
      required: true

# 第二步：全局配置引用这些公共参数，所有接口自动生效
parameters:
  - $ref: '#/components/parameters/AuthorizationHeader'
  - $ref: '#/components/parameters/ConsumerKeyHeader'
  - $ref: '#/components/parameters/CorrelationIdHeader'

paths:
  /some-path:
    get:
      summary: "sample1"
      operationId: doWork
      description: 'description of do work'
      parameters:
        # 这里可以只定义当前接口特有的参数，公共头已经全局生效
        - name: some-query-param
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功响应

  /some-other-path:
    get:
      summary: "sample2"
      operationId: doOtherWork
      description: 'description of do other work'
      responses:
        '200':
          description: 成功响应

方案二：按需引用（部分接口使用） #

如果只有部分接口需要这组头，就在对应接口的parameters里单独引用：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0

components:
  parameters:
    AuthorizationHeader:
      in: header
      name: Authorization
      schema:
        type: string
      required: true
    ConsumerKeyHeader:
      in: header
      name: Consumer-Key
      schema:
        type: string
      required: true
    CorrelationIdHeader:
      in: header
      name: Correlation-Id
      schema:
        type: string
        format: uuid
      required: true

paths:
  /some-path:
    get:
      summary: "sample1"
      operationId: doWork
      description: 'description of do work'
      parameters:
        # 引用公共请求头
        - $ref: '#/components/parameters/AuthorizationHeader'
        - $ref: '#/components/parameters/ConsumerKeyHeader'
        - $ref: '#/components/parameters/CorrelationIdHeader'
        # 加上当前接口特有的参数
        - name: some-query-param
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功响应

  /some-other-path:
    get:
      summary: "sample2"
      operationId: doOtherWork
      description: 'description of do other work'
      parameters:
        # 同样引用公共头
        - $ref: '#/components/parameters/AuthorizationHeader'
        - $ref: '#/components/parameters/ConsumerKeyHeader'
        - $ref: '#/components/parameters/CorrelationIdHeader'
      responses:
        '200':
          description: 成功响应

两种方案的核心都是把公共请求头定义在components/parameters里，通过$ref引用，后续要修改规则时，只需要改components里的定义，所有引用的地方都会同步更新，大幅降低维护成本。

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