引言
在开发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