Spring boot+swagger+bootstrap ui自动化接口文档

1. 什么是Swagger

现在测试都提倡自动化测试，那我们作为后台的开发人员，也得进步下啊，以前用postman来测试后台接口，那个麻烦啊，一个字母输错就导致测试失败，现在swagger的出现可谓是拯救了这些开发人员，便捷之处真的不是一点两点。下面我们看下如何在微服务中将springboot与swagger来结合吧。
简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。

2. 注解说明

@Api()：用于Controller类；表示标识这个类是swagger的资源
@ApiOperation()：用于Controller方法；表示一个http请求的操作
@ApiParam()：用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
@ApiModel()：用于domain、DTO、VO等类，表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()：用于domain、DTO、VO等方法，字段；表示对model属性的说明或者数据操作更改
@ApiIgnore()：用于类，方法，方法参数 表示这个方法或者类被忽略
@ApiImplicitParam()：用于方法表示单独的请求参数
@ApiImplicitParams()：用于方法，包含多个 @ApiImplicitParam

3. 使用

3.1 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.8.5</version>
</dependency>

3.2 添加配置文件

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;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("后台API文档")
                .description("后台API文档")
                .version("1")
                .contact(new Contact("Java","", ""))
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // true-开启文档；false-关闭文档
//                .enable(false)
                .groupName("后台API v1")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller.v1.app"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createAppUserRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)
                .groupName("后台API v2")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller.v2.app"))
                .paths(PathSelectors.any())
                .build();
    }
}

3.3 使用

entity：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("用户信息")
public class User {

    @ApiModelProperty("用户id")
    private String id;

    @ApiModelProperty("登录账号")
    private String loginId;

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("登录密码")
    private String password;

    @ApiModelProperty("性别")
    private Integer gender;

    @ApiModelProperty("电话")
    private String phone;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty("部门id")
    private String department_id;
}

dto和vo：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(value = "分页数据对象")
public abstract class SplitPageDTO {

    @ApiModelProperty(value = "当前页", required = true)
    private Integer page = 0;

    @ApiModelProperty(value = "每页显示数目",example = "10", required = true)
    private Integer pageSize = 10;

    @ApiModelProperty(value = "查找顺序是否为正序", required = true)
    private Boolean asc = false;
}

controller：

import com.xxx.xxx.dto.push.LoginDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@RestController
@Api(tags="后台用户相关【/sysUser】")
@RequestMapping("/sysUser")
public class SysUserController {

   @PostMapping("/passwordLogin")
   @ApiOperation(value = "后台用户密码登录", notes = "使用密码登录")
   public String passwordLogin(@RequestBody LoginDTO dto) {
      
      return null;

   }
}