如何在OpenAPI Spring生成器中控制API标签名称并避免Swagger UI端点重复

问题原因 #

启用useTags=true时，OpenAPI Generator会将spec中的标签名转换为驼峰命名作为API类名（如academic degrees→AcademicDegreesApi），同时默认给类上的@Tag注解使用驼峰后的名称（AcademicDegrees），但接口方法的@Operation(tags)仍保留spec中原有的academic degrees，导致Swagger UI识别为两个不同标签，出现重复端点。

解决方案 #

方案1：使用tagNameMapper参数统一标签名称 #

在Maven插件的configOptions中添加tagNameMapper配置，将类上驼峰形式的标签名映射为spec中原有的名称：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>你的插件版本（推荐6.x及以上）</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/你的openapi文件.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <configOptions>
                    <useTags>true</useTags>
                    <!-- 映射驼峰类标签名到原spec的标签名 -->
                    <tagNameMapper>AcademicDegrees=academic degrees</tagNameMapper>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

配置后生成的AcademicDegreesApi类上的@Tag注解会变为@Tag(name = "academic degrees")，与方法上的@Operation(tags)完全一致，Swagger UI将不再显示重复端点。

方案2：自定义API类模板（适用于参数不生效场景） #

如果tagNameMapper参数无法满足需求，可以自定义Mustache模板修改类上的@Tag注解：

1. 复制OpenAPI Generator Spring生成器的api.mustache模板到项目的src/main/resources/templates目录
2. 修改模板中@Tag注解的名称部分，将驼峰名称替换为原spec的标签名：
   原模板代码：

   {{#apiInfo}}{{#tags}}@Tag(name = "{{name}}"){{/tags}}{{/apiInfo}}
   

   修改为：

   {{#apiInfo}}{{#tags}}@Tag(name = "{{originalName}}"){{/tags}}{{/apiInfo}}
   

3. 在Maven插件配置中指定模板目录：

   <configOptions>
       <useTags>true</useTags>
       <templateDirectory>${project.basedir}/src/main/resources/templates</templateDirectory>
   </configOptions>
   

注意事项 #

• 保留spec中的标签可确保API类名按分组需求生成（如AcademicDegreesApi），避免移除标签后类名变为EducationApi的问题。
• 确保使用的OpenAPI Generator插件版本支持上述配置（建议使用最新稳定版）。

内容的提问来源于stack exchange，提问作者Frederik Højlund