OpenAPI 3.0中如何定义带多属性的公共Header参数

• OpenAPI 3.0 对不同位置参数的序列化规则有强制约束：style: matrix 是仅允许用于 in: path 路径参数的序列化方式，header 位置的参数仅支持 style: simple（默认值，无需显式声明），你给header参数配置matrix样式直接触发了规范校验错误，才会出现位置值不被允许的报错。
• 除了序列化样式不匹配外，OpenAPI 3.0 本身不支持header参数通过object类型schema+explode配置自动生成键值对拼接格式，你预期的id1=uuid1;id2=uuid3属于自定义字符串结构，无法靠对象类型参数自动序列化实现。

最通用、全工具兼容的写法是将该请求头的schema定义为字符串类型，可通过正则约束格式，确保传入值符合要求，定义一次后可在所有接口中通过$ref引用：

openapi: 3.0.3

components:
  parameters:
    customHeader:
      name: "X-Custom"
      in: header
      required: true
      description: 公共自定义请求头，固定格式为 id1=<uuid>;id2=<uuid>
      schema:
        type: string
        # 正则校验，确保头值符合id1、id2为UUID的格式要求
        pattern: '^id1=[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12};id2=[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
        example: id1=123e4567-e89b-12d3-a456-426614174000;id2=987e6543-e21b-43c2-d654-123456789012

引用时只需要在对应接口的parameters数组中添加如下配置即可，无需重复定义头结构：

parameters:
  - $ref: '#/components/parameters/customHeader'

如果使用的文档预览工具支持content字段定义媒体类型结构，也可以用如下写法，文档可读性更强，但部分低版本工具可能存在兼容问题：

components:
  parameters:
    customHeader:
      name: "X-Custom"
      in: header
      required: true
      content:
        text/plain:
          schema:
            type: object
            required: [id1, id2]
            properties:
              id1:
                type: string
                format: uuid
              id2:
                type: string
                format: uuid
          example: id1=123e4567-e89b-12d3-a456-426614174000;id2=987e6543-e21b-43c2-d654-123456789012

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