前面介绍了如何Spring Boot 快速打造Restful API 接口，也介绍了如何优雅的实现 Api 版本控制，不清楚的可以看我之前的文章：https://www.cnblogs.com/zhangweizhong/category/1657780.html
在实际项目中，Api 接口系统对接过程中，Api 接口文档是非常重要的文档。一般是设计完成之后，同时编写Api 接口文档，然后将接口文档发给相关人员，于是大家就按照该文档开发、集成并最终上线。但是，这是一种非常理想的状态，实际开发中，接口不断变化，接口文档也必须保持更新，这是一个非常麻烦的过程！为了解决这些问题，Swagger2 应运而生。接下来，就和大伙聊一聊 Spring Boot 如何整合Swagger2，使用Swagger2构建 RESTful API文档。
什么是Swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。是世界上最流行的 API 表达工具 。我们知道，RESTful API 可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web前端开发等。为了减少与其他团队平时开发期间的频繁沟通成本，一般我们会创建一份API文档来记录所有接口细节，但是api 接口文档存在以下问题：
- 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），要创建这样一份高质量的文档本身就是件非常吃力的事。
- 随着需求的不断变化，接口文档也必须同步修改，这很容易导致文档和业务不一致情况出现。
为了解决这些问题，Swagger2 应运而生。它可以轻松的整合到Spring Boot 中，自动生成强大的 RESTful API文档。这样既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了完整的测试页面，来调试每个API 接口。
下面就以SpringBoot中集成Swagger为例做介绍说明Swagger2 的功能和作用。
Spring Boot 实现Swagger 2
Spring Boot 集成 Swagger 2很简单，首先新建一个 SpringBoot 项目，这里就不重新创建项目，直接使用之前的rest 测试项目。然后引入依赖并做基础配置即可：
1、配置Swagger2的依赖
在pom.xml 配置文件中，增加Swagger 2 的相关依赖，具体如下：
<!-- swagger2 依赖配置-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
注意，swagger 2 的版本号和 spring boot的版本号有些不匹配，最开始用2.2的版本和spring boot 的版本还不匹配，后来把 swagger 2 换成了2.8。
2、创建Swagger 2配置类
在com.weiz.config 包中，增加Swagger 2 的配置类，SwaggerConfig 类，具体代码如下：
package com.weiz.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; 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 Swagger2Config implements WebMvcConfigurer { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.weiz.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .description("Spring Boot相关文章请关注：https://www.cnblogs.com/zhangweizhong") .termsOfServiceUrl("https://www.cnblogs.com/zhangweizhong") .contact("架构师精进") .version("1.0") .build(); } /** * swagger增加url映射 * @param registry */ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
说明：@Configuration 注解让Spring boot来加载该类配置，@EnableSwagger2注解启用Swagger 2，通过配置一个Docket Bean，配置映射路径和要扫描的接口的位置。apiInfo，主要配置一下Swagger2文档网站的信息，例如网站的title、网站的描述、使用的协议等等。
注意：
1、basePackage 可以在SwaggerConfig 里面配置 com.weiz.controller，也可以在启动器里面 ComponentScan 配置。
2、需要在swaggerconfig 中配置swagger 的url 映射。
3、添加文档说明内容
上面配置完成之后，接下来需要在api 接口上增加内容说明。这里方便起见，就直接在之前的UserController 中，增加相应的接口内容说明，代码如下所示：
package com.weiz.controller; import com.weiz.pojo.SysUser; import com.weiz.service.UserService; import com.weiz.utils.JSONResult; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.n3r.idworker.Sid; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; @Api(tags = {"用户接口"}) @RestController @RequestMapping("/") public class UserController { @Autowired private UserService userService; @Autowired private Sid sid; @ApiOperation(value="创建用户", notes="根据User对象创建用户") @PostMapping(value = "user") public JSONResult create(@RequestBody SysUser user) throws Exception { String userId = sid.nextShort(); user.setId(userId); userService.saveUser(user); return JSONResult.ok("保存成功"); } @ApiOperation(value="更新用户详细信息", notes="根据id来指定更新对象，并根据传过来的user信息来更新用户详细信息") @PutMapping(value = "user") public JSONResult update(@RequestBody SysUser user) { userService.updateUser(user); return JSONResult.ok("保存成功"); } @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象") @DeleteMapping("user/{userId}") public JSONResult delete(@PathVariable String userId) { userService.deleteUser(userId); return JSONResult.ok("删除成功"); } @ApiOperation(value="查询用户",notes = "通过用户ID获取用户信息") @GetMapping("user/{userId}") public JSONResult queryUserById(@PathVariable String userId) { return JSONResult.ok(userService.queryUserById(userId)); } }
说明：
1、@Api注解，用来给整个controller 增加说明。
2、@ApiOperation注解，用来给各个API 方法增加说明。
3、@ApiImplicitParams、@ApiImplicitParam注解，用来给参数增加说明。
4、Swagger 还有用于对象参数的注解，对象参数的描述也可以放在实体类中。这里不细说，大家可以自行研究。
测试验证
完成上面的配置和代码修改之后，Swagger 2 就集成到Spring boot 项目中了，接下来启动Spring Boot程序，访问：http://localhost:8088/swagger-ui.html
最后
以上，就把Spring Boot 如何整合Swagger2，使用Swagger2构建 RESTful API文档 介绍完了。实现还是比较简单的，但是还是需要理解里面的相关注解的用法。
这个系列课程的完整源码，也会提供给大家。大家关注我的微信公众号（架构师精进），回复：springboot源码。获取这个系列课程的完整源码。