本教程详细阐述了在Spring Boot项目中正确集成和配置API文档工具Swagger UI的方法，着重推荐使用现代化的springdoc-openapi-ui库。文章涵盖了从引入依赖、移除旧有配置到访问API文档和UI界面的完整流程，并提供了代码示例和注意事项，旨在帮助开发者高效解决“No mapping for GET /swagger-ui.html”等常见问题，提升API开发与调试效率。
引言
在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.gradledependencies { // 移除所有 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示例:
Clipfly
一站式AI视频生成和编辑平台，提供多种AI视频处理、AI图像处理工具。
129 查看详情 
<!-- io.springfox springfox-swagger2 3.0.0 io.springfox springfox-swagger-ui 3.0.0 --> org.springdoc springdoc-openapi-ui 1.6.4
移除旧配置:由于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提供清晰、交互式的文档。
以上就是Spring Boot应用中Swagger UI访问路径的正确配置与实践的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/748656.html
微信扫一扫 
支付宝扫一扫 
