Swagger

1、Swagger：是一套基于OpenAPI规范（OpenAPI Specification，OAS）构建的开源工具，号称世界上最流行的API框架。

2、Swagger Codegen：可以将描述文件生成HTML格式和CWIKI形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

3、Swagger UI：提供了一个可视化的UI页面展示描述文件。

4、Swagger Editor：编辑Swagger描述文件的编辑器。

5、Swagger Inspector：可以对接口进行测试。

6、Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。

7、Springfox Swagger：是Spring社区维护的一个项目。Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。

SpringBoot整合Swagger3的步骤

1、新建SpringBoot-Web项目。

2、导入Swagger依赖。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

3、创建HelloWorldController。

@RestController
public class HelloWorldController {
    @GetMapping("/hello")
    public String hello() {
        return "success";
    }
}

4、创建Swagger配置类。

@Configuration // 配置类
@EnableOpenApi // 开启Swagger的自动配置
public class SwaggerConfiguration {

}

5、访问Swagger页面。

6、Swagger2和Swagger3的配置差异：

（1）SpringBoot项目整合swagger2需要用到两个依赖：springfox-swagger2和springfox-swagger-ui，用于自动生成swagger文档。

（2）Swagger3添加注解@EnableOpenApi，Swagger2是添加注解@EnableSwagger2

（3）Swagger3和Swagger2的访问地址不同。

Swagger配置

1、Swagger配置类常见配置内容：

（1）通过配置Docket实例来配置Swaggger。

（2）可以通过apiInfo()属性配置文档信息。

@Configuration // 配置类
@EnableOpenApi // 开启Swagger的自动配置
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置是否启用Swagger，如果是false，在浏览器将无法访问
                .enable(true)
                // 通过.select()方法，去配置扫描接口
                .select()
                // RequestHandlerSelectors配置要扫描接口的方式
                // basePackage(): 指定要扫描的包
                // any(): 扫描全部
                // none(): 不扫描
                // withClassAnnotation(): 扫描类上的注解，参数是一个注解的反射对象
                // withMethodAnnotation(): 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.duo.controller"))
                // path():过滤什么路径
                //.paths(PathSelectors.ant("/controller/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("多仔", "https://www.l5v.cn/", "[email protected]");
        return new ApiInfo(
                "Swagger API接口文档", // 标题
                "测试项目的Swagger API接口文档", // 描述
                "v2.0", // 版本
                "https://www.l5v.cn/", // 组织链接
                contact, // 联系人信息
                "Apache 2.0 许可", // 许可
                "http://www.apache.org/licenses/LICENSE-2.0", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

2、Swagger常用注解：

（1）Model上的注解：

@ApiModel("用户实体")
public class UserPojo {
    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String password;

    // 省略有参无参get/set
}

（2）Controller上的注解：

@RestController
@Api(tags = "HelloWorld控制类")
public class HelloWorldController {
    @ApiOperation("获取用户信息接口")
    @GetMapping("/getUser")
    public UserPojo getUser() {
        return new UserPojo("admin", "admin");
    }

    @ApiOperation("欢迎信息接口")
    @GetMapping("/hello")
    public String hello(@ApiParam(value = "用户名" ,required = true) String username) {
        return "欢迎你，" + username;
    }
}

（3）查看效果：

3、Swagger配置生产环境与正式环境：

//获取当前环境需要用到environment对象
@Bean
public Docket docket(Environment environment){
    //设置要显示的Swagger环境，是否处于dev或test环境
    Profiles profiles = Profiles.of("dev","test");

    // spring.profiles.active=dev

    //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //是否开启swagger
        .enable(flag)
// 省略其他代码

4、配置SwaggerAPI文档分组：

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        // ...
        .groupName("李华")
        .enable(false);
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("李四")
            // ...
            .enable(true);
    }

// ...

}