【亲测免费】 Springdoc-OpenAPI 常见问题解决方案

项目基础介绍

Springdoc-OpenAPI 是一个用于自动化生成 API 文档的 Java 库，特别适用于 Spring Boot 项目。它通过在运行时检查应用程序来推断 API 语义，基于 Spring 配置、类结构和各种注解来生成 API 文档。生成的文档可以以 JSON/YAML 和 HTML 格式呈现，并且可以通过 Swagger-API 注解进行补充。

该项目主要使用 Java 编程语言，同时也支持 Kotlin 和其他语言。

新手使用注意事项及解决方案

1. 依赖版本不匹配

问题描述：新手在使用 Springdoc-OpenAPI 时，可能会遇到依赖版本不匹配的问题，导致项目无法正常启动或生成文档。

解决步骤：

1. 检查 Spring Boot 版本：确保你的 Spring Boot 版本与 Springdoc-OpenAPI 兼容。例如，Springdoc-OpenAPI v2.x 支持 Spring Boot 3.x，而 v1.x 支持 Spring Boot 2.x 和 1.x。
2. 更新依赖：在 pom.xml 或 build.gradle 文件中，确保引用了正确的 Springdoc-OpenAPI 版本。例如：

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.6.0</version>
   </dependency>
   

3. 清理和重建项目：在更新依赖后，清理并重建你的项目，确保所有依赖项正确加载。

2. Swagger UI 无法访问

问题描述：配置完成后，Swagger UI 页面无法访问，通常是因为配置错误或端点未正确暴露。

解决步骤：

1. 检查配置文件：确保在 application.properties 或 application.yml 中正确配置了 Swagger UI 的端点。例如：

   springdoc.swagger-ui.path=/swagger-ui.html
   

2. 暴露端点：确保你的 Spring Security 配置允许访问 Swagger UI 端点。例如：

   @Override
   protected void configure(HttpSecurity http) throws Exception {
       http.authorizeRequests()
           .antMatchers("/swagger-ui/**").permitAll()
           .anyRequest().authenticated();
   }
   

3. 重启应用：完成配置后，重启你的 Spring Boot 应用，确保配置生效。

3. API 文档未生成

问题描述：项目启动后，API 文档未生成，Swagger UI 页面显示为空。

解决步骤：

1. 检查注解：确保你的控制器类和方法上使用了正确的 Swagger 注解，如 @Operation、@ApiResponse 等。
2. 配置扫描包：在配置类中指定需要扫描的包路径，确保 Springdoc-OpenAPI 能够找到你的控制器。例如：

   @Bean
   public OpenAPI customOpenAPI() {
       return new OpenAPI()
           .info(new Info().title("My API").version("1.0"));
   }
   

3. 检查日志：查看应用启动日志，检查是否有关于 API 文档生成的错误信息，根据日志提示进行调整。

通过以上步骤，新手可以解决在使用 Springdoc-OpenAPI 项目时常见的问题，确保项目能够正常生成和展示 API 文档。