OpenAPI 3与openapi-generator Maven插件生成XML数组DTO的JAXB注解问题

场景描述 #

基于OpenAPI 3.0.3规范编写YAML Schema，使用org.openapitools:openapi-generator-maven-plugin:6.6.0生成Java DTO，用于JAXB反序列化XML响应。服务返回的XML结构如下：

<Response>
<Statements count="5">
    <Statement label="" id="1"/>
    <Statement label="" id="2"/>
    ...
</Statements>
</Response>

原YAML定义存在错误，导致生成的Java类注解不符合预期：

Response:
  type: object
  xml:
    name: 'Response'
  properties:
    Statements:
      $ref: '#/components/schemas/Statements'

Statements:
  type: array
  items:
    $ref: '#/components/schemas/Statement'
  xml:
    name: 'Statements'
    wrapped: true
  properties:  # 违反OpenAPI规范，array类型不能包含properties字段
    count:
      type: integer
      xml:
        attribute: true

Statement:
  type: object
  xml:
    name: 'Statement'
  properties:
    label:
      type: string
      xml:
        attribute: true
    SubAttribute:
      $ref: ...

生成的Java类中，列表字段的注解错误：

public class Response {

  @XmlElement(name = "statements")  // 应为"Statement"
  @XmlElementWrapper(name = "Statements")
  private List<Statement> statements;
  
  ...
}

问题原因 #

1. 违反OpenAPI规范：Statements被定义为array类型，同时添加了properties字段（count属性），这不符合OpenAPI 3.0的schema规则——array类型的schema不能包含properties，因此openapi-generator无法正确解析这个混合定义。
2. 元素名称默认转换：插件默认会将schema中的字段名转为驼峰小写作为XML元素名，原YAML中array的字段名是Statements，生成的元素名变成了statements，和实际XML中的<Statement>标签不匹配，导致JAXB无法识别列表元素。

解决方案 #

调整OpenAPI YAML结构，将带属性的数组包装为对象，而非直接在array上添加属性，符合规范的写法如下：

Response:
  type: object
  xml:
    name: 'Response'
  properties:
    Statements:
      $ref: '#/components/schemas/Statements'

Statements:
  type: object
  xml:
    name: 'Statements'
  properties:
    count:
      type: integer
      xml:
        attribute: true
    Statement:  # 定义数组字段，对应XML中的<Statement>元素
      type: array
      items:
        $ref: '#/components/schemas/Statement'
      xml:
        name: 'Statement'  # 指定XML元素名，避免默认转换

Statement:
  type: object
  xml:
    name: 'Statement'
  properties:
    label:
      type: string
      xml:
        attribute: true
    SubAttribute:
      $ref: ...

生成的正确Java类示例 #

调整后生成的Response类和Statements类会包含正确的JAXB注解：

public class Response {

  @XmlElement(name = "Statements")
  private Statements statements;
  
  ...
}

public class Statements {

  @XmlAttribute(name = "count")
  private Integer count;

  @XmlElement(name = "Statement")
  private List<Statement> statement;
  
  ...
}

这样JAXB就能正确识别XML中的<Statements>标签及其内部的<Statement>元素，完成反序列化。

内容的提问来源于stack exchange，提问作者François Vanhille