在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-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是目前Spring Boot社区中推荐的OpenAPI 3（Swagger 3）集成方案。它具有以下显著优势：
引入依赖: 首先，你需要将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项目中Swagger UI的集成过程，有效避免“No mapping for GET /swagger-ui.html”等常见错误。其强大的自动配置能力、对OpenAPI 3的良好支持以及与Spring Boot的无缝集成，使其成为现代Spring Boot应用中API文档生成的首选方案。遵循本教程的步骤，你将能够快速、高效地为你的RESTful API提供清晰、交互式的文档。
以上就是Spring Boot应用中Swagger UI访问路径的正确配置与实践的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号
140
收藏
