Spring Boot入门系列（二十二）使用Swagger2构建RESTful API文档-技术圈

前面介绍了如何Spring Boot 快速打造Restful API 接口，也介绍了如何优雅的实现 Api 版本控制。

在实际项目中，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@EnableSwagger2public 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、网站的描述、使用的协议等等。

注意：

　basePackage 可以在SwaggerConfig 里面配置 com.weiz.controller，也可以在启动器里面 ComponentScan 配置。
　需要在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源码。获取这个系列课程的完整源码。

Spring Boot入门系列（二十二）使用Swagger2构建RESTful API文档

一、什么是Swagger

二、Spring Boot 实现Swagger 2

三、验证测试

最后

SpringBoot入门系列（三十一）实现静态文件、配置文件与jar分离

SpringBoot入门系列（三十）Spring Boot项目打包、发布与部署

SpringBoot入门系列（二十九）如何使用JdbcTemplate操作数据库？

SpringBoot入门系列（二十八）使用Redis实现分布式Session共享

Spring Boot入门系列（二十一）如何优雅的设计Rest API版本号，实现API版本控制

Spring Boot入门系列（十九）集成mybatis，使用注解实现动态Sql、参数传递等常用操作！

Spring Boot入门系列（十八）mybatis 使用注解实现增删改查，无需xml文件

Spring Boot入门系列（十七）Mybatis创建自定义mapper 实现多表关联查询！

Spring Boot入门系列（十六）整合pagehelper，一秒实现分页功能！

Spring Boot入门系列（十五） SpringBoot开发环境热部署的配置

Spring Boot入门系列（十三）统一日志处理！

Spring Boot入门系列（十一）如何整合Mybatis，实现增删改查【XML 配置版】

Spring Boot入门系列（十）如何使用拦截器，一学就会！

SpringBoot入门系列（三）SpringBoot资源文件属性配置

SpringBoot入门系列（二）Controller介绍及如何返回json数据

SpringBoot入门系列（一）如何快速创建SpringBoot项