本文详解为何 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阶段，以保障文档与实际运行态严格一致。
