Spring Boot(16)：让你的API文档更亮眼：Spring Boot与Swagger-UI完美整合！-CFANZ编程社区

🏆本文收录于《Spring Boot从入门到精通》，专门攻坚指数提升，2023 年国内最系统+最强（更新中）。

本专栏致力打造最硬核Spring Boot 系列教程，从零基础到进阶系列学习内容，🚀均为全网独家首发，打造精品专栏，专栏持续更新中…欢迎大家订阅持续学习。

环境说明：Windows10 + Idea2021.3.2 + Jdk1.8 + SpringBoot 2.3.1.RELEASE

1. 前言

在实际开发过程中，我们经常需要编写API文档来描述接口的调用方法、参数、返回值等信息。为了提高开发效率和维护便利性，Swagger-UI成为了API文档自动生成的一种流行方案。本文将介绍如何利用Spring Boot和Swagger-UI实现在线API文档。

2. 摘要

本文主要涉及以下内容：

Swagger-UI的介绍
Spring Boot整合Swagger-UI
示例代码和测试方法
总结

3. Swagger-UI简介

Swagger是一套用于描述RESTful API的语言和工具集，它包括了一个规范和各种工具，可以帮助我们生成、文档化和测试RESTful API。Swagger-UI则是Swagger的一个用户界面，可以让我们通过浏览器快速浏览和测试API。

在Swagger中，我们可以使用Swagger注解来描述API的各种元素，例如API的路径、HTTP方法、请求参数、响应信息等。这些注解可以生成JSON格式的API描述文件，然后我们可以利用Swagger-UI将这些JSON文件解析出来生成用户友好的API文档。

4. Spring Boot整合Swagger-UI

Spring Boot和Swagger-UI整合非常简单，只需要按照以下步骤即可。

4.1 添加依赖

首先需要在pom.xml文件中添加Swagger-UI依赖：

<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>

4.2 编写配置类

然后创建一个Swagger配置类，用于配置Swagger相关的选项：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage(com.example.demo.controller))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title(API文档)
            .description(Swagger-UI集成测试)
            .version(1.0.0)
            .build();
    }
}

在这个配置类中，我们通过@EnableSwagger2注解启用Swagger-UI，并使用Docket类来配置Swagger的相关选项。其中，apis方法指定了要扫描的Controller类所在的包，paths方法指定了要扫描的API路径，这里我们使用了通配符表示扫描所有路径。最后，apiInfo方法用于生成API文档的基本信息。

4.3 编写Controller类

最后，我们需要编写一个Controller类来提供API接口：

@RestController
@RequestMapping(/api)
@Api(value = API接口测试, tags = API接口测试)
public class ApiController {
    @ApiOperation(value = 获取用户信息, notes = 根据用户ID获取用户信息)
    @ApiImplicitParams({
        @ApiImplicitParam(name = id, value = 用户ID, required = true, dataType = Long)
    })
    @GetMapping(/user/{id})
    public User getUser(@PathVariable Long id) {
        return new User(id, 张三);
    }
}

示例截图如下：

在这个Controller类中，我们使用了@RestController和@RequestMapping注解来定义一个基本的API接口，然后我们使用了Swagger提供的注解来描述API的各种元素，例如@Api注解用于描述API的名称和类别，@ApiOperation注解用于描述API的名称和说明，@ApiImplicitParams注解用于描述API的参数信息。

4.4 运行测试

最后，运行Spring Boot应用程序，然后在浏览器中访问http://localhost:8080/swagger-ui.html，就可以看到生成的API文档了。现在，我们已经可以使用Swagger-UI测试我们的API文档了。

在Swagger-UI中选择“User”，点击“GET /users/”，点击“Try it out”，点击“Execute”，查看响应，现在，我们已经可以使用Swagger-UI测试我们的API文档了，可以通过Swagger-UI方便地查阅我们的API文档，也可以在线测试API，这对于API的开发和测试非常有帮助。示例截图如下：

5. 总结

在本文中，我们介绍了如何使用Spring Boot整合Swagger-UI实现在线API文档。我们使用了Maven构建工具，以及Spring Boot和Swagger-UI框架，帮助开发者快速地生成API文档，并提供在线测试功能。我们使用了一个示例来说明如何编写API文档、添加Swagger注解，并在Swagger-UI中测试API。使用Swagger-UI可以帮助开发者更好地理解和使用API。

关于我