Swagger

一、介绍

OpenAPI 规范 (OAS) 为 RESTful API 定义了一个标准的、与语言无关的接口，它允许人类和计算机在不访问源代码、文档或通过网络流量检查的情况下发现和理解服务的功能。正确定义后，消费者可以使用最少的实现逻辑理解远程服务并与之交互。

文档生成工具可以使用 OpenAPI 定义来显示 API，代码生成工具可以使用各种编程语言、测试工具和许多其他用例来生成服务器和客户端。

二、SpringBoot集成Swagger

1.新建一个SpringBoot-web项目

2.添加maven依赖

<!--        导入swagger3.0-->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-boot-starter</artifactId>
     <version>3.0.0</version>
</dependency>

3、编写HelloController，测试确保运行成功！

4、要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger

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

5、访问测试 ：http://localhost:8080/swagger-ui (swagger2 访问 http://localhost:8080/swagger-ui.html )

三、配置Swagger

1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger

@Bean
public Docket docket() {
   return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo());
}

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

//配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("小智", "http://www.baidu.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "Swagger-api测试", // 描述
                "v1.0", // 版本
                "https://www.baidu.com/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

四、配置扫描接口

1、构建Docket时通过select()方法配置怎么扫描接口

@Bean
public Docket docket() {
   return new Docket(DocumentationType.OAS_30)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
      .build();
}

此外还有很多扫描方法

any()	扫描所有，项目中的所有接口都会被扫描到
none()	不扫描接口
通过方法上的注解扫描	如withMethodAnnotation(GetMapping.class)只扫描get请求
通过类上的注解扫描	如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
basePackage(final String basePackage)	根据包路径扫描接口

2.配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口

.paths(PathSelectors.ant("/xiaozhi/**"))

此外还有过滤方法

any()	任何请求都扫描
none()	任何请求都不扫描
regex(final String pathRegex)	通过正则表达式控制
ant(final String antPattern)	通过ant()控制

3.配置Swagger开关

.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问,默认开启

4.配置Swagger开关小实例

分别配置两套启动环境

application.properties

spring.profiles.active=dev

application-dev.properties

server.port=8080

application-pro.properties

server.port=8080

配置SwaggerConfig

@Bean //配置docket以配置Swagger具体参数
    public Docket docket(Environment environment) {
        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean blug = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.OAS_30)
                .enable(blug)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaozhi.controller"))
                .build()
                ;
    }

五、配置API分组

1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket() {
   return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
      .groupName("xiaozhi") // 配置分组
       // 省略配置....
}

2.配置多个分组

@Bean
public Docket docket1() {
   return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
      .groupName("xiaozhi1") // 配置分组
       // 省略配置....
}
@Bean
public Docket docket2() {
   return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
      .groupName("xiaozhi2") // 配置分组
       // 省略配置....
}
@Bean
public Docket docket3() {
   return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
      .groupName("xiaozhi3") // 配置分组
       // 省略配置....
}

六、实体配置

1、新建一个实体类

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

2、只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中

@GetMapping("/getUser")
    public User getUser(){
        return new User();
    }

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

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

七、常用注解

Swagger注解	简单说明
@Api(tags = "xxx模块说明")
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

八、注意

正式环境要记得关闭Swagger

正式环境要记得关闭Swagger

正式环境要记得关闭Swagger