我们提供Restful接口的时候，API文档是尤为的重要，它承载着对接口的定义，描述等，本文主要介绍了SpringBoot集成Swagger2生成接口文档的方法示例，需要的朋友们下面随着小编来一起学习学习吧

我们提供Restful接口的时候，API文档是尤为的重要，它承载着对接口的定义，描述等。它还是和API消费方沟通的重要工具。在实际情况中由于接口和文档存放的位置不同，我们很难及时的去维护文档。个人在实际的工作中就遇到过很多接口更新了很久，但是文档却还是老版本的情况，其实在这个时候这份文档就已经失去了它存在的意义。而 Swagger 是目前我见过的最好的API文档生成工具，使用起来也很方便，还可以直接调试我们的API。我们今天就来看下 Swagger2 与 SpringBoot 的结合。

文章目录

一、SpringBoot工程创建
二、工程配置
- 2.1. pom依赖配置
- 2.2. Swagger2配置
三、创建接口
四、创建实体类
五、Swagger2 APL介绍
六、页面效果
七、API验证测试
- 7.1. 获取用户列表接口
- 7.2. 创建用户
- 7.3. 根据用户id,获取用户详细信息
- 7.4. 根据用户id,更新用户详细信息
- 7.5. 根据用户id,删除用户信息

一、SpringBoot工程创建

在这里插入图片描述

二、工程配置

2.1. pom依赖配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.1.9.RELEASE</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.gblfy</groupId><artifactId>springboot-swagger2</artifactId><version>0.0.1-SNAPSHOT</version><name>springboot-swagger2</name><description>Spring Boot整合Swagger2</description><properties><!--编码设置--><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><!--JDK版本--><java.version>1.8</java.version></properties><dependencies><!--Spring Boot整合Swagger2 Start--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><!--Spring Boot整合Swagger2 End--><!--Springmvc 启动器--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!--生成get/set等--><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.10</version></dependency><!--单元测试--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies><build><plugins><!--maven编译打包插件--><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build></project>

2.2. Swagger2配置

提供一个Docket的Bean即可

package com.gblfy.springbootswagger2.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @author gblfy* @ClassNme SwaggerConfig* @Description SwaggerConfig 配置bean类* @Date 2019/11/5 20:19* @version1.0*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {/*** 创建一个Docket对象* 调用select()方法，* 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口* 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理** @return*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).pathMapping("/").select().apis(RequestHandlerSelectors.basePackage("com.gblfy.springbootswagger2")).paths(PathSelectors.any()).build().apiInfo(new ApiInfoBuilder()//标题.title("SpringBoot2.x整合Swagger2 构建api文档")//简介.description("简单优雅的restfun风格，详细信息......")//版本.version("9.0")//作者个人信息.contact(new Contact("技术论坛", "https://gblfy.com", "gblfy@gmail.com")).license("The Apache License")//服务条款.licenseUrl("https://gblfy.com").build());}
}

这里提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。

如此，Swagger2就算配置成功了，非常方便。

此时启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：
在这里插入图片描述

三、创建接口

接下来就是创建接口了，Swagger2相关的注解其实并不多，而且很容易懂，下面我来分别向小伙伴们举例说明：

package com.gblfy.springbootswagger2.controller;import com.gblfy.springbootswagger2.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;import java.util.*;/*** @author gblfy* @ClassNme UserController* @Description 用户管理接口* @Date 2019/11/5 20:26* @version 1.0*/
@Api(tags = "用户管理相关接口")
@RestController
@RequestMapping(value = "/user")
public class UserController {// 创建线程安全的Map 用户封装用户数据public static Map<Long, User> userList = Collections.synchronizedMap(new HashMap<Long, User>());/*** 获取用户列表 封装公用** @return*/@ApiOperation(value = "获取用户列表", notes = "这里填写接口方法描述")@GetMapping("/list")public List<User> getUserList() {// 处理"/userList/"的GET请求，用来获取用户列表// 还可以通过@RequestParam从页面中传递参数来进行查询条件或者翻页信息的传递List<User> users = new ArrayList<User>(userList.values());return users;}/*** 创建用户** @param user* @return*/@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")@PostMapping("/")public String postUser(@RequestBody User user) {// 处理"/userList/"的POST请求，用来创建User// 除了@ModelAttribute绑定参数之外，还可以通过@RequestParam从页面中传递参数userList.put(user.getId(), user);return "success";}/*** 根据用户id,获取用户详细信息** @param id* @return*/@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")@GetMapping(value = "/{id}")public User getUser(@PathVariable Long id) {// 处理"/userList/{id}"的GET请求，用来获取url中id值的User信息// url中的id可通过@PathVariable绑定到函数的参数中return userList.get(id);}/*** 根据用户id,更新用户详细信息** @param id* @param user* @return*/@ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")})@PutMapping(value = "/{id}")public String putUser(@PathVariable Long id, @ModelAttribute User user) {// 处理"/userList/{id}"的PUT请求，用来更新User信息User u = userList.get(id);u.setUserName(user.getUserName());u.setAge(user.getAge());userList.put(id, u);return "success";}/*** 根据用户id,删除用户信息** @param id* @return*/@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")@DeleteMapping(value = "/{id}")public String deleteUser(@PathVariable Long id) {// 处理"/userList/{id}"的DELETE请求，用来删除UseruserList.remove(id);return "success";}
}

四、创建实体类

package com.gblfy.springbootswagger2.entity;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;/*** @author gblfy* @ClassNme User* @Description TODO* @Date 2019/11/5 20:31* @version1.0*/
@ApiModel
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class User {@ApiModelProperty(value = "用户id")private long id;@ApiModelProperty(value = "用户名")private String userName;@ApiModelProperty(value = "用户年龄")private Integer age;
}

五、Swagger2 APL介绍

注解	说明
@Api	用来标记当前Controller的功能
@ApiOperation	用来标记一个方法的作用
@ApiImplicitParam	用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替
@ApiImplicitParams	如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中
@RequestParam(required = true)	，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略
@ApiModel	如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中
@ApiModelProperty	用户成员变量中