openapi-generator不读取tags的description导致生成文件及swagger-ui不显示问题

这个问题的根本原因是openapi-generator的默认Java代码生成模板没有主动渲染全局tag的description字段，解析阶段已经正常读取到了该配置，只需调整配置或模板即可解决。

方案一：使用内置配置项（适用于openapi-generator版本≥5.3.0） #

你已经开启了useTags=true，只需要额外新增一个配置参数即可：

• 在你的生成配置的configOptions中添加 tagDescriptionAsApiDescription: true

Maven插件配置示例：

<configOptions>
    <useTags>true</useTags>
    <tagDescriptionAsApiDescription>true</tagDescriptionAsApiDescription>
    <!-- 其余原有配置保持不变 -->
</configOptions>

Gradle插件配置示例：

configOptions = [
    useTags: "true",
    tagDescriptionAsApiDescription: "true",
    // 其余原有配置保持不变
]

配置完成后重新生成代码，@Api注解的description会自动替换为你在OpenAPI定义文件中tags模块下配置的描述内容，swagger-ui也可以正常读取展示。

方案二：自定义模板（适用于低版本不支持上述配置项的场景） #

如果你的openapi-generator版本较低没有内置上述参数，可以通过修改控制器生成模板实现：

1. 从openapi-generator官方仓库下载对应语言的控制器模板，Java Spring场景对应的模板文件是api.mustache
2. 找到模板中生成@Api注解的代码行，将description属性的取值替换为{{#tags}}{{description}}{{/tags}}，替换后示例如下：

@Api(value = "{{classname}}", description = "{{#tags}}{{description}}{{/tags}}")

3. 在生成配置中指定templateDirectory参数为你存放修改后模板的本地目录，重新执行生成命令即可生效。

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