Swagger入门--整合Springboot

1.简介
在前后端分离的背景下，前后端通过API进行交互，前后端相对独立且松耦合。因此前后端集成时，前端或者后端问题无法做到及时协商沟通，最终导致问题集中爆发。
swagger可以很好的解决此问题。在项目开发中，根据业务代码自动生成API文档，给前端提供在线测试，自动显示JSON格式，方便了后端与前端的沟通与调试成本。Swagger有一个缺点就是侵入性模式，必须配置在具体的代码里。

2.环境搭建
导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <!--API 获取的包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <!--官方给出的一个ui界面，这个界面可以自定义，默认是官方的 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

编写swaggerConfig配置类

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的默认页面。

3.配置Swagger
SwaggerConfig.java配置类

@Configuration //此类是一个配置类
@EnableSwagger2 //开启swagger2的自动配置
public class SwaggerConfig {

    //Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger
    private ApiInfo apiInfo() {
        Contact contact = new Contact("kwhua", "http:www.baidu.com", "310697723@qq.com");
        return new ApiInfoBuilder()
                .title("演示Swagger生成接口文档") //文档标题
                .description("演示使用swagger") //文档描述
                .contact(contact)
                .version("v1.0.0")//版本
                .build();
    }
//配置多个分组
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("user")
                .select()
                .paths(PathSelectors.none())
                .build();
    }

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("dept")//配置分组
                .enable(true)//配置是否启用Swagger，如果是false，在浏览器将无法访问,默认是true
                .select() //配置扫描的接口
                //.apis(RequestHandlerSelectors.none())
                .paths(PathSelectors.any())
                .build();
    }
}

另外、apis和paths的扩展用法

.apis(RequestHandlerSelectors.any())//项目中的所有接口都会被扫描到
.apis(RequestHandlerSelectors.none())//不扫描接口
.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
.apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
.apis(RequestHandlerSelectors.basePackage("com.kwhua.controller"))//RequestHandlerSelectors配置如何扫描接口


.paths(PathSelectors.any())//任何接口都扫描
.paths(PathSelectors.none()) //什么接口都不扫描
.paths(PathSelectors.regex(Regex))//通过正则表达式控制
.paths(PathSelectors.ant("/api/**")// 配置如何通过path过滤,即这里只扫描请求以/api开头的接口

实体类Dept.java

@Getter
@Setter
@ToString
@ApiModel("部门实体")
/**
 * @ApiModel为类添加注释
 * @ApiModelProperty为类属性添加注释
 */
public class Dept {
    @ApiModelProperty("部门id")
    private Integer id;
    @ApiModelProperty("部门名称")
    private String deptName;
    @ApiModelProperty("部门编号")
    private Integer deptNo;
    @ApiModelProperty("部门地址")
    private String deptAddr;
}

控制层DeptController.java

@RestController
@Api("部门信息")
public class DeptController {
    @Autowired
    private DeptService deptService;

    @PostMapping("/findById")
@ApiOperation(value = "获取部门信息",notes = "通过id获取部门信息")
//只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：
    public Dept findById(@RequestParam("部门id") Integer id) {
        Dept dept = deptService.findById(id);
        return dept;
    }
}

再次测试：http://localhost:8080/swagger-ui.html 。

接口信息

实体信息

注：并不是因为实体类的@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
Swagger常用注解

Swagger注解	说明
@Api(tags = “xxx模块说明”)	作用在模块类上，表示标识这个类是swagger的资源
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxx实体类说明”)	作用在实体类上
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty
@ApiIgnore()	用于类，方法，方法参数 表示这个方法或者类被忽略