如何通过OpenAPI 3.0与Swagger Codegen V3生成版本专属API方法

要实现每个请求体版本对应单独的@Consumes注解，核心是把同一路径下不同Content-Type的请求拆分为独立的OpenAPI Operation，而不是在单个Operation里包含多个content变体。Swagger Codegen V3默认会把单个Operation下的所有Content-Type合并到每个重载方法的@Consumes中，拆分Operation是解决问题的关键。

1. 调整OpenAPI YAML结构 #

将原来的单个Operation拆分为多个独立的Operation，每个Operation对应一个版本的Content-Type，并为每个Operation指定唯一的operationId（避免生成方法名冲突）。

示例YAML代码：

paths:
  /your-target-path:
    # 对应版本1.0.0的请求
    post:
      operationId: createResourceV1
      requestBody:
        required: true
        content:
          application/json;version=1.0.0:
            schema:
              $ref: '#/components/schemas/Object1'
      responses:
        '200':
          description: Success response
    # 对应版本2.0.0的请求
    post:
      operationId: createResourceV2
      requestBody:
        required: true
        content:
          application/json;version=2.0.0:
            schema:
              $ref: '#/components/schemas/Object2'
      responses:
        '200':
          description: Success response

2. 配置Swagger Codegen Maven插件 #

确保插件配置中启用useOperationIdAsMethodName参数，这样生成的方法名会直接使用你定义的operationId，既避免重载冲突，又能让每个方法绑定对应的Content-Type。

插件配置示例：

<plugin>
  <groupId>io.swagger.codegen.v3</groupId>
  <artifactId>swagger-codegen-maven-plugin</artifactId>
  <version>3.0.34</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
        <language>java</language>
        <configOptions>
          <useOperationIdAsMethodName>true</useOperationIdAsMethodName>
          <!-- 其他自定义配置参数 -->
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

3. 最终生成效果 #

按照上述配置生成后，你会得到两个独立的方法，每个方法的@Consumes只包含对应版本的Content-Type，完全符合你的预期：

@Consumes({ "application/json;version=1.0.0" })
public void createResourceV1(Object1 body) {
    // 方法实现
}

@Consumes({ "application/json;version=2.0.0" })
public void createResourceV2(Object2 body) {
    // 方法实现
}

原方式不生效的原因 #

Swagger Codegen V3对单个Operation下的多个content类型，会将其视为同一个接口的请求体变体，因此生成的重载方法会共享该Operation下的所有Content-Type，这就是为什么你之前看到两个方法都包含两个@Consumes值的原因。只有拆分Operation，才能让每个方法绑定独立的Content-Type。

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