引言
在spring boot项目中开发restful api时，为api生成交互式文档是提高开发效率和协作质量的关键。swagger（或openapi）是广泛使用的api文档工具。然而，许多初学者或从旧版本迁移的项目可能会遇到“no mapping for get /swagger-ui.html”的错误，导致无法访问swagger ui界面。这通常是由于依赖配置不当、版本不兼容或缺少正确的mvc资源映射导致的。本教程将提供一套清晰、现代化的解决方案，推荐使用springdoc-openapi-ui库，它与spring boot的自动配置机制无缝集成，极大地简化了swagger的设置过程。
问题分析：Springfox与映射错误
用户提供的代码片段中，使用了springfox-swagger2和springfox-swagger-ui这两个依赖，并配置了Docket Bean。springfox是一个较早的Swagger集成库，在某些Spring Boot版本或特定配置下，尤其是在没有正确处理静态资源映射时，可能会导致swagger-ui.html无法被正确映射。
例如，在用户提供的TasksApplication中，存在@EnableWebMvc注解。虽然在某些情况下这可能是必要的，但在Spring Boot应用中，它会禁用Spring Boot的默认Web MVC自动配置。这意味着你需要手动配置许多东西，包括静态资源处理器，而这正是Swagger UI所需的。springfox在处理静态资源方面有时需要更精细的配置，尤其是在@EnableWebMvc存在时。
推荐方案：使用Springdoc OpenAPI UI
springdoc-openapi-ui是目前Spring Boot社区中推荐的OpenAPI 3（Swagger 3）集成方案。它具有以下显著优势：
- 自动配置: 与Spring Boot的自动配置机制深度集成，通常无需编写任何额外的Java配置代码即可工作。
- 兼容性: 更好地支持Spring Boot 2.x及更高版本，以及OpenAPI 3规范。
- 简化: 极大地简化了Swagger的设置和使用过程。
核心步骤
-
引入依赖: 首先，你需要将springdoc-openapi-ui依赖添加到你的项目构建文件中。请确保移除所有旧的springfox相关依赖，以避免潜在的冲突。
Gradle示例:
// build.gradle dependencies { // 移除所有 springfox 相关的依赖，例如： // implementation 'io.springfox:springfox-swagger2:3.0.0' // implementation 'io.springfox:springfox-swagger-ui:3.0.0' // 添加 springdoc-openapi-ui 依赖 implementation 'org.springdoc:springdoc-openapi-ui:1.6.4' // 建议使用最新稳定版本 }Maven示例:
<!-- pom.xml --> <dependencies> <!-- 移除所有 springfox 相关的依赖，例如： --> <!-- <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0</version> </dependency> --> <!-- 添加 springdoc-openapi-ui 依赖 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.4</version> <!-- 建议使用最新稳定版本 --> </dependency> </dependencies> -
移除旧配置: 由于springdoc-openapi-ui的自动配置特性，你通常不需要像springfox那样手动创建Docket Bean。因此，请移除项目中所有与springfox相关的配置类，例如用户提供的CoreConfiguration类中的Docket Bean。
// 移除 CoreConfiguration 类中与 Docket 相关的配置 // @Configuration // @EnableSwagger2 // 这个注解也不再需要 // public class CoreConfiguration { // // ... // @Bean // public Docket api() { // return new Docket(DocumentationType.SWAGGER_2) // .select() // .apis(RequestHandlerSelectors.any()) // .paths(PathSelectors.any()) // .build(); // } // } -
关于 @EnableWebMvc: 在Spring Boot应用程序中，通常不需要在主应用程序类上使用@EnableWebMvc注解。Spring Boot的自动配置会为你处理Web MVC的大部分配置，包括静态资源处理。如果添加了@EnableWebMvc，它会禁用这些自动配置，可能导致Swagger UI的静态资源无法被正确加载。除非你有非常特殊的MVC配置需求，否则建议将其移除。
package com.crud.tasks; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; // import org.springframework.web.servlet.config.annotation.EnableWebMvc; // 建议移除此注解 @SpringBootApplication // @EnableWebMvc // 如果非必要，请移除此行 public class TasksApplication { public static void main(String[] args) { SpringApplication.run(TasksApplication.class, args); } } -
访问API文档与UI界面: 完成上述配置后，启动你的Spring Boot应用。springdoc-openapi-ui会自动暴露API文档和Swagger UI界面。
OpenAPI 3 API 文档 (JSON/YAML): 默认路径为：http://localhost:your_port/v3/api-docs
Swagger UI 界面: 默认路径为：http://localhost:your_port/swagger-ui.html 或者 http://localhost:your_port/swagger-ui/index.html (取决于具体版本和配置，通常swagger-ui.html会重定向到index.html)
请将your_port替换为你的Spring Boot应用实际运行的端口号（默认为8080）。
-
自定义路径 (可选): 如果你想自定义API文档的路径，可以在application.properties或application.yml中进行配置：
application.properties:
springdoc.api-docs.path=/api-docs
这将把API文档的访问路径改为 http://localhost:your_port/api-docs。Swagger UI的路径也会相应调整，通常会保持swagger-ui.html不变，但它会根据api-docs的路径来查找API定义。
注意事项与常见问题
- 版本兼容性: 确保你使用的springdoc-openapi-ui版本与你的Spring Boot版本兼容。通常，在Maven Central或Gradle Plugin Portal上可以找到最新的稳定版本。
- 端口号: 确保你访问的localhost:your_port中的端口号与你的Spring Boot应用实际监听的端口一致。
- 多模块项目: 如果是多模块项目，请确保springdoc-openapi-ui依赖被正确地添加到了包含Controller的模块中。
- Spring Security: 如果你的项目使用了Spring Security，可能需要配置安全规则以允许对/v3/api-docs/**和/swagger-ui/**路径的访问。
总结
通过采用springdoc-openapi-ui库，你可以极大地简化Spring Boot项目中Swagger UI的集成过程，有效避免“No mapping for GET /swagger-ui.html”等常见错误。其强大的自动配置能力、对OpenAPI 3的良好支持以及与Spring Boot的无缝集成，使其成为现代Spring Boot应用中API文档生成的首选方案。遵循本教程的步骤，你将能够快速、高效地为你的RESTful API提供清晰、交互式的文档。
