SpringBoot实战(07)：整合Swgger2文档框架

一、介绍

开发过程中，除了日常的功能开发任务以外，维护接口文档也是一项必不可少的事情。接口开发者以文档的形式描述的接口的功能，并随着接口功能不断迭代也随着更新。但是实际情况往往比较糟糕，常常出现接口文档未能及时更新导致接口文档描述和接口本身不符的情况；也存在由于接口文档没有统一格式，导致后期查看是无法理解接口的含义。

那么有没有一个文档框架可以帮忙我们更便捷的生成接口文档呢，Swagger2 就是这样一个比较好用的文档框架。Swagger2 是一款 RESTful 接口文档在线生成的文档框架。一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，加上 Swagger-ui，可以有很好的呈现。下面我们实战操作如何在 SpringBoot 中使用该框架。

二、添加 Swgger2 依赖

在 pom.xml 中加入 Swagger2 的依赖。

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

<!-- swagger2-UI-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

三、添加 Swagger 配置文件

添加依赖后，我们就可以开始使用 Swagger 框架整合接口文档了，首先我们需要添加配置文件 SwaggerConfig.java 配置文件。

package com.shiyanlou.upms.common.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger 配置文件
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 该处填写本项目的 controller
                .apis(RequestHandlerSelectors.basePackage("com.ming.upms.system.controller")) 
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 标题
                .title("管理系统API接口文档")
                // 作者信息
                .contact(new Contact("jie_ming514", "https://blog.csdn.net/m1090760001", "jie_ming514@163.com"))
                // 描述
                .description("管理系统API接口文档")
                // 版本
                .version("1.0.0")
                .build();
    }
}

启动项目后，输入 http://localhost:8080/swagger-ui.html ,可以查看 Swagger2是否添加成功。

四、添加接口说明

配置完成后，我们就可以正常使用了，使用的方式也非常简单，只需要在类和方法上添加响应的注解即可。

@Api(tags = "用户管理")
@Controller
@RequestMapping("/user")
public class UpmsUserController {

    @ApiOperation("用户管理主页")
    @Log("用户管理页面")
    @GetMapping("/main")
    String UpmsUser(){
       // 方法内容略
    }

    @ApiOperation("用户信息分页列表")
    @Log("用户管理分页列表")
    @ResponseBody
    @GetMapping("/list")
    public PageUtils list(@RequestParam Map<String, Object> params){
        // 方法内容略
    }
}

这里边涉及到多个 API，我来向小伙伴们分别说明。

1. @Api 注解可以用来标记当前 Controller 的功能。
2. @ApiOperation 注解用来标记一个方法的作用。
3. @ApiImplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4. 如果有多个参数，则需要使用多个 @ApiImplicitParam 注解来描述，多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。

重新启动项目后，输入 http://localhost:8080/swagger-ui.html ,我们可以看到新的文档列表中有了我们添加的中文描述信息了。

五、对象模型的文档说明

除了对类和接口的说明以外，我们还可以对对象模型进行文档说明。此时我们可以通过 @ApiModel 和 @ApiModelProperty 注解对一个自定义类进行接口说明。

// 新导入的包
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "用户实体类")
public class UpmsUser implements Serializable {
    @ApiModelProperty(value = "账号", name = "userId", example = "123")
    private Integer userId;
    @ApiModelProperty(value = "用户名", name = "username")
    private String username;
    @ApiModelProperty(value = "密码MD5(密码+盐)", name = "password")
    private String password;
    @ApiModelProperty(value = "盐", name = "salt")
    private String salt;
    @ApiModelProperty(value = "姓名", name = "realname")
    private String realname;
    @ApiModelProperty(value = "头像", name = "avatar")
    private String avatar;
    @ApiModelProperty(value = "电话", name = "phone")
    private String phone;
    @ApiModelProperty(value = "邮箱", name = "email")
    private String email;
    @ApiModelProperty(value = "性别", name = "sex", example = "0")
    private Byte sex;
    @ApiModelProperty(value = "状态(0:正常,1:锁定)", name = "locked", example = "1")
    private Byte locked;
    @ApiModelProperty(value = "创建时间", name = "ctime")
    private Date ctime;
    @ApiModelProperty(value = "所属机构", name = "organizationId", example = "123")
    private Integer organizationId;

    // 省略set get 方法
}

重新启动项目后，输入 http://localhost:8080/swagger-ui.html , 点击打开方法后，我们可以看到对象模型也进行了详细的描述。

相比与手工编写的接口文档，通过 Swagger2 生成的文档更简洁、更规范，同时编写起来要比传统手工方式更方便、更快捷。

六、总结

当然 Swagger2 生成文档的同时，也带来了一个新的问题，即给代码带来了一堆的注解，使得方法和实体类变得很臃肿。如果项目决定使用 Swagger2 框架后，可以删除备注使用 Swagger2 注解，并且尽量使用对象模型方式，减少在方法的描述。

博客的内容是根据平时在写项目代码后的知识点总结。既是对自己的一个总结，也是给大家的一点小小分享，希望大家多多支持！如有问题希望大家多多指教。谢谢！