如何避免为同时支持XML和JSON的API重复定义Schema？

我正在为包含多类型标签集合的文档资源定义API，每个标签类型对应独立的属性集。现有XSD定义如下：

<complexType name="Document">
    <sequence>
        <element name="description" type="xs:string" minOccurs="0"/>
        <element name="tags" type="TagsList" minOccurs="0"/>
    </sequence>
</complexType>
<complexType name="TagsList">
    <choice minOccurs="0" maxOccurs="unbounded">
        <any processContents="lax" namespace="http://www.example.com/schema/tags"/>
    </choice>
</complexType>

对应的XML示例：

<document>
  <description>the description</description>
  <tags>
    <tagA>
      <propA1>...</propA1>
      <propA2>...</propA2>
      ...
    </tagA>
    <tagB>
      <propB1>...</propB1>
      <propB2>...</propB2>
      ...
    </tagB>
    ...
  </tags>
</document>

这个API同时支持XML和JSON格式。直接序列化XML到JSON会丢失标签类型信息，所以我用适配器生成了保留类型的JSON响应——XML里的tags是标签列表，JSON里则是按标签类型索引的映射表。但这导致OpenAPI文档需要为同一资源定义两套组件，关联对象也得重复定义，产生大量冗余。

• 抽离公共字段+媒体类型专属Schema
  将description这类公共字段抽成通用Schema，仅针对差异化的tags字段定义XML和JSON专属结构，通过allOf组合，最后用oneOf统一对外暴露。这样核心字段只定义一次，避免重复：

  components:
    schemas:
      DocumentCore:
        type: object
        properties:
          description:
            type: string
            nullable: true
      DocumentXml:
        allOf:
          - $ref: '#/components/schemas/DocumentCore'
          - type: object
            properties:
              tags:
                type: array
                items:
                  type: object
                  additionalProperties: true
            xml:
              name: document
              wrapped: true
      DocumentJson:
        allOf:
          - $ref: '#/components/schemas/DocumentCore'
          - type: object
            properties:
              tags:
                type: object
                additionalProperties:
                  type: object
      Document:
        oneOf:
          - $ref: '#/components/schemas/DocumentXml'
          - $ref: '#/components/schemas/DocumentJson'
  

  在API响应里，针对不同媒体类型指定对应Schema：

  paths:
    /documents/{id}:
      get:
        responses:
          '200':
            description: 成功获取文档
            content:
              application/xml:
                schema:
                  $ref: '#/components/schemas/DocumentXml'
              application/json:
                schema:
                  $ref: '#/components/schemas/DocumentJson'
  

• 用OpenAPI 3.1的xml扩展兼容双格式
  OpenAPI 3.1支持在Schema中通过xml扩展定义XML专属结构，同时保留JSON的映射格式，同一个Schema就能覆盖两种场景，依赖序列化工具（如Jackson、JAXB）的配置实现转换：

  components:
    schemas:
      Document:
        type: object
        properties:
          description:
            type: string
            nullable: true
          tags:
            # JSON侧：标签类型为键的映射表
            type: object
            additionalProperties:
              type: object
            # XML侧：转为标签列表
            xml:
              name: tags
              wrapped: true
              items:
                xml:
                  name: tag
                  namespace: http://www.example.com/schema/tags
  

• 统一序列化格式（最简洁）
  如果业务允许，把XML和JSON的tags结构统一成列表形式，每个标签对象带type字段标识类型。这样两种格式结构一致，OpenAPI只需要一套Schema，彻底消除冗余：
  调整后的XML示例：

  <document>
    <description>the description</description>
    <tags>
      <tag type="tagA">
        <propA1>...</propA1>
        <propA2>...</propA2>
      </tag>
      <tag type="tagB">
        <propB1>...</propB1>
        <propB2>...</propB2>
      </tag>
    </tags>
  </document>
  

  对应的JSON：

  {
    "description": "the description",
    "tags": [
      {
        "type": "tagA",
        "propA1": "...",
        "propA2": "..."
      },
      {
        "type": "tagB",
        "propB1": "...",
        "propB2": "..."
      }
    ]
  }
  

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