让你的API文档更亮眼：Spring Boot与Swagger-UI完美整合！

bug菌

修改于 2023-09-27 16:21:30

2.4K00

代码可运行

文章被收录于专栏：《项目实战教学》《项目实战教学》

运行总次数：0

代码可运行

🏆本文收录于《 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。