引言
在开发RESTful风格的Web应用程序时，自动生成API文档是一项非常有用的功能。Swagger是一个流行的API文档生成工具，它能够方便地生成可读性良好的文档，并提供了友好的UI界面来展示和测试API。本文将介绍如何在Spring Boot项目中集成Swagger3，并创建一个精美的UI界面来展示API文档。
什么是Swagger？
Swagger是一组开源工具和规范，用于设计、构建、记录和使用RESTful风格的Web服务。它通过注解和自动文档生成来简化API开发过程，并提供了一个可视化的界面来测试和验证API。
Spring Boot集成Swagger3
在Spring Boot项目中，集成Swagger3非常简单。只需要添加相关的依赖项，并配置Swagger的一些基本信息即可。
1. 添加Swagger3依赖
在项目的pom.xml中添加以下依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2. 配置Swagger
在Spring Boot的配置类中添加Swagger的配置信息：
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controllers"))
.paths(PathSelectors.any())
.build();
}
}
在上述代码中，RequestHandlerSelectors.basePackage需要设置为你的控制器类所在的包。
3. 启动应用程序
运行Spring Boot应用程序，并访问http://localhost:8080/swagger-ui.html即可看到Swagger的UI界面。
美化Swagger UI
默认情况下，Swagger UI界面可能会显得有些普通。为了美化UI，我们可以使用Swagger UI官方提供的样式主题。
1. 下载样式主题
从上述链接下载Swagger UI的样式主题，并解压到项目的src/main/resources/static目录下。
2. 修改Swagger配置
修改SwaggerConfig类中的api方法，添加样式主题相关的配置信息。
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controllers"))
.paths(PathSelectors.any())
.build()
.pathMapping("/")
.apiInfo(apiInfo())
.useDefaultResponseMessages(false)
.enableUrlTemplating(false)
.extensions(Collections.singletonList(new SwaggerUIExtension()))
.tags(new Tag("sample", "Sample Operations"));
}
@Bean
public UiConfiguration uiConfig() {
return UiConfigurationBuilder.builder()
.deepLinking(true)
.displayOperationId(false)
.defaultModelsExpandDepth(1)
.defaultModelExpandDepth(1)
.build();
}
@Bean
public WebMvcConfigurerAdapter webMvcConfigurerAdapter() {
return new WebMvcConfigurerAdapter() {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/3.25.0/")
.resourceChain(false);
}
};
}
在上述代码中，我们使用了自定义的SwaggerUIExtension类来添加额外的样式表和脚本。
3. 重新启动应用程序
重新运行Spring Boot应用程序并访问http://localhost:8080/swagger-ui.html，你会看到UI已经变得更加美观而且更具吸引力。
结论
通过集成Swagger3，我们可以轻松地为我们的Spring Boot应用程序生成精美的API文档和测试界面。通过以上的步骤，你可以快速集成Swagger3并美化UI界面。希望本篇博客对你有所帮助，祝你使用Swagger开发愉快！
本文来自极简博客，作者：星空下的约定，转载请注明原文链接：Spring Boot集成Swagger3：打造精美的API文档UI
