本文详解为何 swagger-maven-plugin 生成空 OpenAPI 文件（仅 { "openapi": "3.0.1" }），并提供基于 springdoc-openapi-maven-plugin 的可靠替代方案，通过启动嵌入式服务+运行时抓取方式导出完整、准确的 OpenAPI 3 JSON 规范。
本文详解为何 `swagger-maven-plugin` 生成空 openapi 文件（仅 `{ "openapi": "3.0.1" }`），并提供基于 `springdoc-openapi-maven-plugin` 的可靠替代方案，通过启动嵌入式服务+运行时抓取方式导出完整、准确的 openapi 3 json 规范。
io.swagger.core.v3:swagger-maven-plugin 是一个静态源码扫描型插件，它依赖 JAX-RS 注解（如 @Path, @GET）和 Swagger 2.x 风格注解（如 @Api, @ApiOperation），无法识别 Spring MVC + Springdoc OpenAPI 3 的 @Operation/@Tag 等注解。即使你已正确添加 springdoc-openapi-ui 依赖并在运行时通过 /v3/api-docs 提供完整文档，该插件在编译期扫描时仍无法解析 Spring Boot 的控制器结构，导致输出仅为 OpenAPI 版本声明的空骨架。
✅ 正确做法：改用 org.springdoc:springdoc-openapi-maven-plugin —— 它专为 Springdoc 设计，采用运行时 HTTP 抓取机制，在 Maven 构建生命周期中自动启动应用、请求 /v3/api-docs 接口，并保存真实响应内容。
✅ 推荐配置（Maven pom.xml）
<profiles><profile><id>generate-openapi</id><build><plugins><!-- 1. 启动 Spring Boot 应用（集成测试阶段） --><plugin><groupid>org.springframework.boot</groupid><artifactid>spring-boot-maven-plugin</artifactid><version>3.2.0</version><!-- 建议匹配项目 Spring Boot 版本 --><executions><execution><id>pre-integration-test</id><goals><goal>start</goal></goals></execution><execution><id>post-integration-test</id><goals><goal>stop</goal></goals></execution></executions></plugin><!-- 2. 抓取运行中的 OpenAPI 文档 --><plugin><groupid>org.springdoc</groupid><artifactid>springdoc-openapi-maven-plugin</artifactid><version>1.5.0</version><!-- 兼容 Spring Boot 3.x；若用 SB 2.x，选 1.3.x --><executions><execution><phase>integration-test</phase><goals><goal>generate</goal></goals></execution></executions><configuration><apidocsurl>http://localhost:8080/v3/api-docs</apidocsurl><outputfilename>openapi-spec.json</outputfilename><outputdir>${project.basedir}/generated-swagger</outputdir><skip>false</skip></configuration></plugin><!-- （可选）生成 HTML 文档 --><plugin><groupid>io.swagger.codegen.v3</groupid><artifactid>swagger-codegen-maven-plugin</artifactid><version>3.0.46</version><executions><execution><phase>post-integration-test</phase><goals><goal>generate</goal></goals><configuration><inputspec>${project.basedir}/generated-swagger/openapi-spec.json</inputspec><language>html</language><output>${project.basedir}/generated-swagger/html</output></configuration></execution></executions></plugin></plugins></build></profile></profiles>
⚠️ 关键注意事项
-
端口与路径必须匹配：确保
<apidocsurl></apidocsurl>中的地址与你的应用实际暴露的 OpenAPI 文档路径一致（默认为http://localhost:8080/v3/api-docs；若自定义了server.port或springdoc.api-docs.path，请同步更新）。 -
依赖版本对齐：
springdoc-openapi-maven-plugin版本需与springdoc-openapi-starter-webmvc-api（或springdoc-openapi-ui）兼容：- Spring Boot 3.x → 使用
springdoc-openapi-starter-webmvc-api:2.3.0++springdoc-openapi-maven-plugin:1.5.0+ - Spring Boot 2.6–2.7 → 使用
springdoc-openapi-ui:1.6.14+springdoc-openapi-maven-plugin:1.3.2
- Spring Boot 3.x → 使用
-
避免静态插件干扰：请移除
io.swagger.core.v3:swagger-maven-plugin，防止其与运行时方案冲突。 -
确保控制器被扫描：确认
@RestController类位于 Spring Boot 主类同包或子包下，或通过@ComponentScan显式包含。
✅ 验证方式
执行以下命令触发完整流程：
mvn clean verify -Pgenerate-openapi
构建成功后，检查 ${project.basedir}/generated-swagger/openapi-spec.json —— 此文件将与浏览器访问 http://localhost:8080/v3/api-docs 所见内容完全一致，包含所有 @Tag、@Operation、参数、响应等完整定义。
? 小技巧：如需跳过测试阶段快速生成，可临时将
<phase></phase>改为verify并确保应用能独立启动；但生产环境强烈建议保留integration-test阶段，以保障文档与实际运行态严格一致。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
