SpringBoot整合Swagger2自动生成Api文档

现在前后端分离式的开发已经成为一种趋势，在这样的一种开发模式下，对于前端来说接口文档就显得尤为重要，回想起在我之前的公司，我们都是在word里写接口文档，这样其实会存在很多问题，比如繁琐，风格不统一，极大的增加了后端开发的工作量，后来接触了Swagger，是真的非常的方便好用，所以分享一下。

生成后的文档大概是这个样子

页面非常的干净简洁，也很美观，接下来就开始搭建这个Api文档

一、引入依赖

首先我们需要引入Swagger的依赖

	io.springfox
	springfox-swagger2
	2.9.2


	io.springfox
	springfox-swagger-ui
	2.9.2

二、编写配置文件

package priv.cwr.user.config;

import org.springframework.beans.factory.annotation.Value;
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;

/**
 * @Description Swagger配置类
 * @Author CWR
 * @Date 2020/2/11 15:53
 */

@Configuration      //标记配置类
@EnableSwagger2     //开启在线接口文档
public class SwaggerConfig {
    /**
     * 读取配置文件是否开启Swagger(如果配置文件没有该字段则会报错)
     */
    @Value("${swagger.show}")
    private boolean swaggerShow = false;

    /**
     * api接口包扫描路径(Controller的路径)
     */
    private static final String SWAGGER_SCAN_BASE_PACKAGE = "priv.cwr.user.controller";

    /**
     * 版本号
     */
    private static final String VERSION = "V1.0.0";

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("cwr-blog-user")
                .description("cwr-blog-user")
                .version(VERSION)
                .build();
    }

    /**
     * 添加摘要信息(Docket)
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerShow)
                .groupName("cwr-blog-user")
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
}

这个配置比较简单，直接用就可以，有时间也可以去研究一下，这里还可以配置请求头等等

三、编写文档

要形成我们自定义的Api文档主要需要这几个注解：

        @Api：用于描述类(Controller)
        @ApiOperation：用于描述方法
        @ApiParam：用于描述方法传入的参数
        @ApiModelProperty：用于描述类的成员变量

下面我贴一下我的示例代码

UserController.java

package priv.cwr.user.controller;

import com.github.pagehelper.Page;
import io.swagger.annotations.*;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import priv.cwr.platform.common.component.Errors;
import priv.cwr.platform.common.exception.ApiException;
import priv.cwr.platform.common.vo.PageNumber;
import priv.cwr.platform.common.vo.Result;
import priv.cwr.user.entity.model.UserModel;
import priv.cwr.user.entity.viewmodel.UserViewModel;
import priv.cwr.user.service.UserService;

import java.util.List;

/**
 * @author chenwenrui
 * @description: 用户Controller
 * @date 2019/6/5 17:08
 */

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

    /**
     * 添加用户
     *
     * @param viewModel 用户ViewModel
     * @return
     */
    @PostMapping
    @ApiOperation(value = "添加用户")
    public void add(@RequestBody UserViewModel viewModel) {
  
    }

    /**
     * 删除用户
     *
     * @param id 用户id
     * @return
     */
    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户")
    public boolean delete(@ApiParam(name = "id", value = "用户id", required = true) @PathVariable Long id) {
       
    }

    /**
     * 批量删除用户
     *
     * @param ids 用户id集合
     * @return
     */
    @PostMapping("/batch-delete")
    @ApiOperation(value = "批量删除用户")
    public boolean batchDelete(@RequestBody List ids) {
		
    }

    /**
     * 修改用户
     *
     * @param userViewModel 用户ViewModel
     * @return
     */
    @PutMapping
    @ApiOperation(value = "修改用户")
    public void update(@RequestBody UserViewModel userViewModel) {
	
    }

    /**
     * 通过id查询用户实体
     *
     * @param id 用户id
     * @return
     */
    @GetMapping("/{id}")
    @ApiOperation(value = "用户详情")
    public UserViewModel findById(@ApiParam(name = "id", value = "用户id", required = true) @PathVariable Long id) {
     
    }

    /**
     * 查询用户列表
     *
     * @param page     分页参数
     * @param pagesize 分页参数
     * @return
     */
    @GetMapping
    @ApiOperation(value = "用户列表")
    public List findList(@ApiParam(name = "page", value = "页数") @RequestParam(value = "page", required = false) Integer page,
                                    @ApiParam(name = "pagesize", value = "页长度") @RequestParam(value = "pagesize", required = false) Integer pagesize,
                                    @ApiParam(name = "name", value = "用户姓名") @RequestParam(value = "name", required = false) String name,
                                    @ApiParam(name = "phone", value = "电话") @RequestParam(value = "phone", required = false) String phone,
                                    @ApiParam(name = "gender", value = "性别") @RequestParam(value = "gender", required = false) Integer gender) {
        
    }
}

UserViewModel.java

package priv.cwr.user.entity.viewmodel;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import priv.cwr.platform.entity.viewmodel.BaseViewModel;

import javax.persistence.Column;

/**
 * @author chenwenrui
 * @description: 用户ViewModel
 * @date 2019/8/12 10:36
 */

@Data
public class UserViewModel {
    /**
     * 用户姓名
     */
    @ApiModelProperty(value = "用户姓名", name = "name")
    private String name;

    /**
     * 性别,1:男,2:女,3:未知
     */
    @ApiModelProperty(value = "性别", name = "gender")
    private Integer gender;

    /**
     * 电话
     */
    @ApiModelProperty(value = "电话", name = "phone")
    private String phone;

    /**
     * 邮箱
     */
    @ApiModelProperty(value = "邮箱", name = "email")
    private String email;

    /**
     * 账号
     */
    @ApiModelProperty(value = "账号", name = "accountNumber")
    private String accountNumber;

    /**
     * 密码
     */
    @ApiModelProperty(value = "密码", name = "password")
    private String password;
}

这里只是一个最简单的例子，这些注解还有很多属性，可以自行研究一下。

完成之后访问   http://ip:port/swagger-ui.html  就可以了