swagger-codegen-maven-plugin v3生成API客户端两类异常问题咨询

swagger-codegen v3 基于OpenAPI 3.0规范实现，和v2基于Swagger 2.0规范的解析逻辑、默认配置存在明显差异，两个问题的具体诱因如下：

• 表单参数被错误归类为query参数：v3不再通过接口上的consumes = "application/x-www-form-urlencoded"配置自动推断参数位置，而是严格读取OpenAPI规范文件中的参数定义。OpenAPI 3.0已经废弃了v2版本的formData参数类型，表单类请求的参数必须定义在requestBody节点下。如果从Springfox 2.0迁移时没有将原有Swagger 2.0文档做标准格式转换，原有表单参数会被默认标记为query类型，codegen就会将其放入queryParams；加上v3 Java客户端生成器默认不会对未显式标记位置的参数做表单类型自动归类，最终调用时就会因为参数位置错误、Content-Type不匹配抛出415 UNSUPPORTED_MEDIA_TYPE错误。
• 方法名丢失请求方式后缀：v3版本Java代码生成器默认关闭了HTTP方法后缀的命名规则，v2版本中该规则默认开启，因此会自动给方法名追加UsingGET/UsingPOST这类后缀。

修复表单参数识别错误 #

按以下两步处理：

1. 先确保输入给codegen的OpenAPI 3.0文档符合规范：
   • 如果你是从Springfox 2.0直接迁移，建议替换为springdoc-openapi作为OpenAPI 3.0的扫描组件，针对表单提交接口，给参数显式添加@Parameter(in = ParameterIn.FORM)注解，或用@io.swagger.v3.oas.annotations.parameters.RequestBody标注表单请求体，确保生成的规范文件中表单参数都被正确归类到requestBody节点下。
   • 如果你是复用旧的Swagger 2.0文档，可以先用codegen自带的格式转换功能将Swagger 2.0文档转为标准OpenAPI 3.0格式，确认表单参数结构正确后再生成客户端代码。
2. 在swagger-codegen-maven-plugin v3的配置中添加如下参数，强制开启表单参数识别逻辑：

<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.20</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!-- 保留原有配置 -->
                <configOptions>
                    <!-- 保留原有configOptions配置 -->
                    <useFormParams>true</useFormParams>
                    <disableMultipart>false</disableMultipart>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

恢复方法名的HTTP请求方式后缀 #

直接在插件的configOptions节点中添加如下配置，显式开启带HTTP方法后缀的命名规则即可：

<configOptions>
    <!-- 其他原有配置 -->
    <useMethodNamingWithHttpMethodSuffix>true</useMethodNamingWithHttpMethodSuffix>
</configOptions>

配置调整后执行mvn clean generate-sources，检查生成目录下的API类文件：

• 表单接口的参数是否被放入formParams，且请求自动携带对应的Content-Type头
• 接口方法名是否恢复了UsingPOST/UsingGET这类后缀
  确认生成代码符合预期后再进行业务调用，即可解决上述两个问题。

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