一、传统API接口文档存在问题

1、由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。

2、随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

为了解决上面的问题，可以采用Swagger2。它最大的特色在于，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。

二、Spring Boot整合Swagger2

添加Swagger2依赖

<!-- Swagger2的依赖 --><dependency><!--添加Swagger依赖 --><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><dependency><!--添加Swagger-UI依赖 --><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.7.0</version></dependency>

创建Swagger2配置类

package com.springboot.api.core.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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** * @method Swagger2配置类* @author Mr yi* @time 2019年4月29日*/
@Configuration //标记配置类
@EnableSwagger2 //开启在线接口文档
public class Swagger2Config {/*** 添加摘要信息(Docket)*/@Beanpublic Docket controllerApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.springboot.api.api")).paths(PathSelectors.any()).build();}@SuppressWarnings("deprecation")private ApiInfo apiInfo() {return new ApiInfoBuilder().title("标题：IT菜鸟_接口文档").description("描述：用于IT菜鸟相关项目API接口文档，访问地址：http://localhost:8006/spring-api/swagger-ui.html").contact("Mr yi").version("版本号:v1.0").build();}
}

@Configuration注解：让Spring Boot来加载该类配置。

@EnableSwagger2注解：启用Swagger2。

@Bean注解：让Docket函数创建类型为Docket的Bean

apiInfo()方法：用来创建该API的基本信息（这些信息最后会展现在文档页面中）。

select()函数：返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义——Swagger会扫描该包下（com.springboot.api.api）所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

package com.springboot.api.api.test.controller;import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.springboot.api.api.test.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;@Api(tags = "用户信息接口")
@RestController
@RequestMapping("/user")
public class UserController {/*** 模拟测试数据*/static Map<Integer, User> users = new HashMap<>();static  {User user1 = new User(1, "admin", "123456");User user2 = new User(2, "lisi", "111111");User user3 = new User(3, "wangwu", "123456");users.put(1,user1);users.put(2,user2);users.put(3,user3);}@ApiOperation("获取列表")@RequestMapping(value={""}, method=RequestMethod.GET)public List<User> userList() {List<User> list= new ArrayList<User>();Iterator<Entry<Integer, User>>  iter = users.entrySet().iterator();while (iter.hasNext()) {Entry<Integer, User> entry = iter.next();list.add(entry.getValue());}return list;}@ApiOperation(value="新增用户", notes="根据User对象创建用户")@ApiImplicitParam(name = "User", value = "用户详细实体user", required = true, dataType = "User")@RequestMapping(value="", method=RequestMethod.POST)public User save(User user) {users.put(user.getUserId(), user);return user;}@ApiOperation(value="获取用户详细信息", notes="根据id来获取用户详细信息")@ApiImplicitParam(paramType="path" ,name = "id", value = "用户ID", required = true, dataType = "Integer")@RequestMapping(value="/{id}", method=RequestMethod.GET)public User getUser(@PathVariable Integer id) {return users.get(id);}@ApiOperation(value="更新用户", notes="根据id来指定更新对象，并根据传过来的user信息来更新用户详细信息")@ApiImplicitParams({@ApiImplicitParam(paramType="path" ,name = "id", value = "用户ID", required = true, dataType = "Integer"),@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")})@RequestMapping(value="/{id}", method=RequestMethod.PUT)public User  update(@PathVariable Integer id, @RequestBody User user	) {User u = users.get(id);u.setUsername(user.getUsername());u.setPassword(user.getPassword());users.put(id, u);return u;}@ApiOperation(value="删除用户", notes="根据id来指定删除对象")@ApiImplicitParam(paramType="path" ,name = "id", value = "用户ID", required = true, dataType = "Integer")@RequestMapping(value="/{id}", method=RequestMethod.DELETE)public String deleteUser(@PathVariable Integer id) {users.remove(id);return "success";}}

启动程序

http://localhost:8006/springboot-api/swagger-ui.html

三、Swagger2注解使用教程

@Api：用在请求的类上，表示对类的说明tags="说明该类的作用，可以在UI界面上看到的注解"value="该参数没什么意义，在UI界面上也看到，所以不需要配置"@ApiOperation：用在请求的方法上，说明方法的用途、作用value="说明方法的用途、作用"notes="方法的备注说明"@ApiImplicitParams：用在请求的方法上，表示一组参数说明@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面name：参数名value：参数的汉字说明、解释required：参数是否必须传paramType：参数放在哪个地方· header --> 请求参数的获取：@RequestHeader· query --> 请求参数的获取：@RequestParam· path（用于restful接口）--> 请求参数的获取：@PathVariable· body（不常用）· form（不常用）    dataType：参数类型，默认String，其它值dataType="Integer"       defaultValue：参数的默认值@ApiResponses：用在请求的方法上，表示一组响应@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息code：数字，例如400message：信息，例如"请求参数没填好"response：抛出异常的类@ApiModel：用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）@ApiModelProperty：用在属性上，描述响应类的属性@Api：用在请求的类上，说明该类的作用tags="说明该类的作用"value="该参数没什么意义，所以不需要配置"

---

如果你觉得本篇文章对你有所帮助的话，麻烦请点击头像右边的关注按钮，谢谢！

技术在交流中进步，知识在分享中传播