如何在 OpenAPI 3.0 中定义具有多个属性的 header 参数？

Question

我需要像这样定义一个 header 参数 X-Custom: id1=uuid1;id2=uuid3

因为这是所有路径的通用 header 我想定义一次并每次都引用它。到目前为止，我想到了这个：

openapi: 3.0.3

components:
  parameters:
    customHeader:
      name: "X-Custom"
      in: header           # <--- produces error
      required: true
      schema:
        type: object
        properties:
          id1:
            type: string
            format: uuid
          id2:
            type: string
            format: uuid
      style: matrix
      explode: true

但是我得到一个错误，提示 'header' 是不允许的，并且参数没有显示在预览中。知道出了什么问题吗？

Answer 1

打开API 3 supports 仅 style: simple 用于 header 参数。这意味着 objects 可以通过以下两种方式之一进行序列化：

# {"id1": "uuid1", "id2": "uuid2"} becomes...

# explode: false
X-Custom: id1,uuid1,id2,uuid2

# explode: true
X-Custom: id1=uuid1,id2=uuid2

请注意，这些样式中的 none 与您预期的格式 X-Custom: id1=uuid1;id2=uuid2 匹配，其中 ; 作为分隔符。事实上，OpenAPI 目前没有办法定义 ; 分隔的 header 值。

您最多可以将整个 header 定义为字符串，在 description 中提及 header 值格式，并提供一个 example 值：

    customHeader:
      name: X-Custom
      in: header
      required: true
      schema:
        type: string
      example: id1=uuid1;id2=uuid2

存在改进 Openheader 序列化样式的现有功能请求API:

如果您正在设计新的 API 而不是记录现有的，另一种解决方法是将 header 拆分为两个 header：

X-id1: uuid1
X-id2: uuid2

如何在 OpenAPI 3.0 中定义具有多个属性的 header 参数？

How to define a header parameter with multiple attributes in OpenAPI 3.0?

openapi