swagger-maven-plugin生成空JSON文件：如何导出完整OpenAPI3规范？

问题原因 #

springdoc-openapi-ui能正常渲染完整API文档，但maven插件生成的JSON只有版本号，核心原因是插件配置未正确关联到项目的API定义，或者插件版本与springdoc不兼容，导致插件无法扫描到控制器和注解信息。

解决方案 #

方案一：直接从API接口导出（最快捷） #

既然/v3/api-docs能返回完整JSON，直接通过接口导出即可：

• 启动项目后，访问 http://localhost:8080/v3/api-docs，复制页面返回的全部JSON内容到本地文件。
• 或者用命令行工具一键导出：

  curl http://localhost:8080/v3/api-docs > generated_swagger_apiDoc.json
  

方案二：调整maven插件配置（适合自动化构建） #

如果需要在mvn install时自动生成，需确保插件配置正确，推荐使用springdoc官方的maven插件替代原swagger-maven-plugin（后者对OpenAPI3支持有限）：

1. 在pom.xml中替换插件依赖：

   <plugin>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-maven-plugin</artifactId>
       <version>1.6.0</version> <!-- 版本需与springdoc-openapi-ui匹配 -->
       <executions>
           <execution>
               <id>generate-openapi</id>
               <goals>
                   <goal>generate</goal>
               </goals>
               <configuration>
                   <!-- 本地项目启动后的API文档地址 -->
                   <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
                   <!-- 输出文件名 -->
                   <outputFileName>generated_swagger_apiDoc.json</outputFileName>
                   <!-- 输出目录 -->
                   <outputDir>${project.build.directory}</outputDir>
               </configuration>
           </execution>
       </executions>
   </plugin>
   

2. 如果坚持使用原swagger-maven-plugin，需补充关键配置项：

   <plugin>
       <groupId>io.swagger.core.v3</groupId>
       <artifactId>swagger-maven-plugin</artifactId>
       <version>2.2.15</version>
       <executions>
           <execution>
               <id>resolve-api</id>
               <goals>
                   <goal>resolve</goal>
               </goals>
               <configuration>
                   <outputFileName>generated_swagger_apiDoc.json</outputFileName>
                   <outputPath>${project.build.directory}</outputPath>
                   <!-- 指定你的OpenAPI配置类全路径 -->
                   <configurationClass>com.yourproject.config.OpenAPIConfig</configurationClass>
                   <!-- 指定控制器所在的包路径 -->
                   <scanBasePackages>com.yourproject.controller</scanBasePackages>
                   <prettyPrint>true</prettyPrint>
               </configuration>
           </execution>
       </executions>
   </plugin>
   

3. 执行构建命令：

   mvn clean install
   

   此时生成的JSON文件会包含完整的API定义。

注意事项 #

• 确保springdoc-openapi-ui和maven插件的版本兼容，避免因版本差异导致扫描失败。
• 检查OpenAPI配置类是否正确添加了@OpenAPIDefinition等注解，控制器类的@Operation、@Parameter等注解是否配置完整。

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