引言
在做服务端开发的时候，难免会涉及到API 接口文档的编写，可以经历过手写API 文档的过程，就会发现，一个自动生成API文档可以提高多少的效率。
以下列举几个手写API 文档的痛点：
文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如postman
接口文档太多，不好管理
Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。
系列文档目录
Spring Boot 项目学习 (一) 项目搭建
Spring Boot 项目学习 (二) MySql + MyBatis 注解 + 分页控件 配置
Spring Boot 项目学习 (三) Spring Boot + Redis 搭建
Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档
配置 Swagger
1. 修改pom.xml文件，添加依赖
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2. 添加Swagger2的配置文件Swagger2Config
package com.springboot.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; @Configuration
@EnableSwagger2
public class SwaggerConfig { @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.springboot.controller")) //需要注意的是这里要写入控制器所在的包
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格，https://www.cnblogs.com/jiekzou/")
.termsOfServiceUrl("https://www.cnblogs.com/jiekzou/")
.version("1.0")
.build();
}
}
如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
添加文档内容
在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
package com.springboot.controller; import com.github.pagehelper.PageInfo;
import com.springboot.entity.Church;
import com.springboot.service.ChurchService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List; @Api(value = "团契操作controller", description = "团契相关的操作", tags = {"团契模块校验接口"})
@RestController
@RequestMapping("/church")
public class ChurchController {
@Autowired
private ChurchService churchService; @ApiOperation(value = "获取指定团契信息", notes = "根据传入标识获取详细信息")
@ApiImplicitParam(name = "churchId", value = "团契标识", required = true, dataType = "String", paramType = "path")
@RequestMapping(value = "/get/{churchId}", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
public String getChurch(@PathVariable String churchId) {
Church church = churchService.get(churchId);
return church.toString();
} @ApiOperation(value = "获取团契列表", notes = "获取团契列表")
@RequestMapping(value = "list", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
public List<Church> list() {
return churchService.list();
} @ApiOperation(value = "分页获取团契列表", notes = "获取团契列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "page", value = "第几页", required = true, dataType = "Integer", paramType = "path"),
@ApiImplicitParam(name = "pageSize", value = "每页取几条记录", required = true, dataType = "Integer", paramType = "path")
})
@RequestMapping(value = "/list/{page}/{pageSize}", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
public PageInfo<Church> list(@PathVariable("page") int page, @PathVariable("pageSize") int pageSize) {
return churchService.list(page, pageSize);
}
}
swagger的相关注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数
启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html，最终运行效果如下
