请关注微信公众号：拾荒的小海螺
博客地址：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 {
@Bean
public 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 {
@Autowired
private UserService userService;
@ApiOperation("获取所有用户")
@GetMapping
public List<UserEntity> list() {
return userService.list();
}
@ApiOperation("添加新用户")
@PostMapping
public void save(@RequestBody UserEntity user) {
userService.save(user);
}
@ApiOperation("更新用户信息")
@PutMapping
public 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());
}
5、总结
通过集成Swagger，开发者可以轻松地生成和维护API文档，提高开发效率和API的可用性。在Spring Boot项目中，Swagger的集成过程相对简单，只需添加依赖、配置类和注解即可完成。希望通过本文的介绍，你能够在自己的项目中顺利集成Swagger，为API文档的生成和维护提供便利。
