Swagger使用学习

一、什么是Swagger?

最流行的API框架，是一款RestFul风格 API文档的在线自动生成工具，能使得API文档和API定义同步更新。

讲得简单些，现在是前后端分离时代，前端可以不再依赖后端就能直接运行，而实现前后端交互的过程就是后端在控制层提供一个个API接口，前端通过这些API接口来获取对应的Json数据。现在面临一个问题，如果前端需求发生变化，比如数据表要添加一个字段，前端是很容易做到的，可后端修改起来却很麻烦，尤其是当需求不断变化，而前后端又不能及时沟通，就会使得项目开发延期。而Swagger就是用来解决这个问题的，它能让前端团队及时知道后端的API有哪些变化，从而及时进行修改调整。

二、如何使用Swagger?

这里简单介绍一下在Spring Boot 里使用Swagger的步骤

1、新建一个Spring Boot-web工程，导入Swagger依赖

        <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>

2、编写一个Hello工程，创建一个配置类来配置Swagger ，具体配置内容后面在说

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
}

3、在浏览器里输入以下URL来测试网站是否成功集成了Swagger：http://localhost:8080/swagger-ui.html

4、在之前创建的配置类里配置Swagger

配置Swagger扫描的对象：

    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//swagger基本信息(标题、介绍、联系URL...),默认使用自定义的，也可以自己新建apiInfo()
                .groupName("xlyoung")//配置API的分组，默认为default
                .enable(false) //enable是否启用默认为true,swagger如果为false，则Swagger不能在浏览器中访问
                .select()
                //RequestHandlerSelectors，配置要扫描接口的方式
                //-->basePackage，指定要扫描的包
                //-->any()，扫描全面
                //-->none()，都不扫描
                //-->withClassAnnotation，扫描类上的注解
                //-->withMethodAnnotation，扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.zzq.swagger.controller"))
                //paths过滤什么路径
                .paths(PathSelectors.ant("/zzq/**"))
                .build();
    }


    //如何去配置多个分组，只需要配置多个Docket实例就行
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

5、我们可以在实体类上加一些注释的注解，方便对生成的API文档进行说明和理解

@ApiModel("用户实体类")//该注解用来给类注释，方便用户理解，不加它swagger也会获取到该对象
public class User {
    @ApiModelProperty("姓名")//该注解用来给属性注释，方便用户理解，不加它swagger也会获取到该对象
    private String name;
    @ApiModelProperty("密码")
    private String password;

    //get/set/构造方法省略
}

同样的，我们也可以在控制层里的方法上加上相关注解来为其做注释：

@ApiOperation("保存用户")//注意只能在方法上加这个注解，而不能在类上加
@PostMapping("/saveUser")
public String saveUser(@ApiParam("用户") @RequestBody User user){
    return "保存成功！姓名："+user.getName()+"，密码："+user.getPassword();
}

三、Swagger的测试功能

可以在 http://localhost:8080/swagger-ui.html 页面里对各个API进行在线测试