JAVA：Spring Boot 整合 Swagger 的技术指南

请关注微信公众号：拾荒的小海螺
博客地址：http://lsk-ww.cn/

1、简述

在现代Web开发中，API文档的生成和维护是非常重要的。Swagger是一款流行的API文档生成工具，它可以帮助开发者自动生成API文档，并提供可视化的接口测试功能。本文将介绍如何在Spring Boot项目中集成Swagger，快速生成API文档。

官网地址：https://swagger.io/

在这里插入图片描述

2、准备工作

在开始集成Swagger之前，确保你的开发环境已经安装并配置好了以下工具：

Java JDK：建议使用JDK 8或以上版本。
Maven：用于依赖管理和构建项目。
Spring Boot：确保已有一个Spring Boot项目。

3、集成Swagger

Swagger是一套开源工具，用于设计、构建、文档化和使用RESTful Web服务。通过注解，Swagger可以自动生成功能全面的API文档，提供直观的接口信息和在线测试功能。

3.1 添加Swagger依赖

首先，在你的Spring Boot项目的pom.xml文件中添加Swagger相关的依赖：

<dependencies><!-- Swagger依赖 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency><!-- 其他依赖 -->
</dependencies>

3.2 创建Swagger配置类

在项目中创建一个Swagger配置类，用于配置Swagger的基本信息和扫描路径。新建一个类SwaggerConfig：

package com.xhl.shiro.config;import io.swagger.annotations.ApiOperation;
import io.swagger.models.Contact;
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.List;import static com.google.common.collect.Lists.newArrayList;@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()//加了ApiOperation注解的类，才生成接口文档.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//包下的类，才生成接口文档//.apis(RequestHandlerSelectors.basePackage("com.xhl.shiro.controller")).paths(PathSelectors.any()).build().securitySchemes(security());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API文档").description("Spring Boot 集成 Swagger 示例").version("1.0.0").build();}private List<SecurityScheme> security() {return newArrayList(new ApiKey("token", "token", "header"));}}

在上述配置中，RequestHandlerSelectors.basePackage方法指定了Swagger要扫描的包路径，你可以根据项目结构进行调整。

3.3 集成Swagger UI

在Swagger官网下载最新的UI(https://swagger.io/tools/swagger-ui/download/)：

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui

然后通过npm指令安装和编译：

npm install
npm run build

然后把编译完成在dist目录下的所有文件拷贝到项目/resources/static/swagger：
在这里插入图片描述

3.4 注解控制器类和方法

Swagger通过注解来生成API文档。在控制器类和方法上使用Swagger注解，描述API接口信息。例如：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.List;@Api(tags = "用户管理")
@RestController
@RequestMapping("/users")
public class UserController {@Autowiredprivate UserService userService;@ApiOperation("获取所有用户")@GetMappingpublic List<UserEntity> list() {return userService.list();}@ApiOperation("添加新用户")@PostMappingpublic void save(@RequestBody UserEntity user) {userService.save(user);}@ApiOperation("更新用户信息")@PutMappingpublic void update(@RequestBody UserEntity user) {userService.updateById(user);}@ApiOperation("删除用户")@DeleteMapping("/{id}")public void delete(@PathVariable Long id) {userService.removeById(id);}
}

Swagger常用注解说明：

@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiParam：定义在参数上
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
@ApiImplicitParams: 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiImplicitParam的参数说明：
paramType：指定参数放在哪个地方
header：请求参数放置于Request Header，使用@RequestHeader获取
query：请求参数放置于请求地址，使用@RequestParam获取
path：（用于restful接口）–>请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传 true | false
value：说明参数的意思
defaultValue：参数的默认值

3.5 访问Swagger UI

启动Spring Boot项目后，打开浏览器访问http://localhost:8080/swagger/，你将看到Swagger自动生成的API文档界面。在这个界面中，你可以查看所有API的详细信息，并进行在线测试。

服务端接口文档路径：http://localhost:8080/v2/api-docs，通过Explore导入：

在这里插入图片描述

4、配置Swagger的更多选项

Swagger提供了丰富的配置选项，你可以根据项目需求进行定制。例如：

设置全局参数：可以在Swagger配置类中设置全局的请求头、响应头等。
分组API：通过设置不同的Docket实例，可以将API分组展示。
安全配置：可以集成OAuth2、JWT等认证方式，保护API接口。

@Bean
public Docket customDocket() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.xhl.shiro")).paths(PathSelectors.any()).build().securitySchemes(securitySchemes()).securityContexts(securityContexts());
}