如何用OpenAPI Generator Maven Plugin生成含Servers和Tags的SpringDocConfiguration？

核心结论 #

明确说：完全可以生成servers和tags信息，你遇到的情况大概率是配置没加对或版本兼容问题，不是功能做不了。

具体解决步骤 #

1. 补上关键配置参数 #

虽然官方文档没明说，但Spring生成器需要加特定配置才能触发servers和tags的生成，在Maven插件的<configuration>里的<configOptions>中加这两行：

<configOptions>
  <!-- 开启servers生成 -->
  <springdocUseServerPort>true</springdocUseServerPort>
  <!-- 开启tags生成 -->
  <useTags>true</useTags>
</configOptions>

其中useTags负责把YAML里的tags转成SpringDoc的分组配置，springdocUseServerPort负责将servers信息注入到生成的配置类中。

2. 核对依赖版本 #

确保项目里的springdoc-openapi-starter-webmvc-ui（如果是webflux项目就用对应starter）版本和OpenAPI Generator 7.8.0兼容，最好用2.2.0及以上版本，不然可能因为依赖不匹配，导致生成的配置无法正常加载servers和tags。

3. 手动补全（临时救急） #

要是上面的配置还是没效果，直接修改生成的SpringDocConfiguration类也行：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info().title("你的接口文档标题").version("版本号"))
        // 手动添加servers
        .servers(List.of(new Server().url("/api").description("默认服务地址")))
        // 手动添加tags
        .tags(List.of(new Tag().name("用户管理").description("用户相关接口集合")));
}

关于PR没生效的说明 #

有些标注“已解决”的PR可能没合并到7.8.0的代码分支里，你可以查插件的版本变更日志，确认这个功能是不是真的在7.8.0版本中发布。要是确实没包含，不妨试试升级到更高版本的OpenAPI Generator Maven Plugin，比如8.x系列。

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