Spring Boot（十五）--------Swagger介绍及集成

前后端分离：Vue+SpringBoot后端时代：前端只需要管理静态页面：html、css、js。后端通过模板引擎JSP重写，后端是主力 25.1.1 前后端分离时代

前端：前端控制层，视图层；伪造后端数据，json。不需要后端，前端功能仍旧能跑起来后端：后端控制层（Controller），服务层，数据访问层前后端通过API进行交互，前后端相对独立且松耦合 25.1.2 产生的问题

强后端集成联调，前端或后端无法做到”及时协商，尽早解决“，最终导致问题集中爆发 25.1.3 解决方案

首先定义提纲，并实时跟踪最新的API，降低集成风险早些年：指定word计划文档前后端分离

前端测试后端接口：postman后端提供接口，需要实时更新最新的消息及改动 25.2 Swagger

号称世界上最流行的API框架Restful Api文档在线自动生成器，API文档和API定义同步更新直接运行，在线测试API支持多种语言（如：Java，PHP等）官网：API documentation & Design Tools for Teams | Swagger 25.3 SpringBoot集成Swagger

导入springfox-swagger2和springfox-swagger-ui的jar包使用Swagger时，需要使用jdk1.8+，否则swagger2无法运行新建一个SpringBoot项目，导入web依赖3.0版本之前

   io.springfox
   springfox-swagger2
   2.9.2



   io.springfox
   springfox-swagger-ui
   2.9.2

3.0版本之后，springboot版本2.5.6

   io.springfox
   springfox-boot-starter
   3.0.0

编写HelloController，测试是否运行成功

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

应用主类增加注解@EnableOpenApi

@SpringBootApplication
@EnableOpenApi
public class SwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }

}

测试访问网址：http://localhost:8080/swagger-ui/index.html或http://localhost:8080/swagger-ui/，可以看到swagger页面

新建一个SwaggerConfig类，并且加上注解@Configuration

Swagger的Bean实例是Docket，所以通过配置Docket实例来配置Swagger，可以通过apiInfo()属性配置文档信息

@Configuration
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){

        return new Docket(documentationType.OAS_30)
                .apiInfo(apiInfo());
    }
    //配置Swagger信息apiInfo()
    private ApiInfo apiInfo(){
        return new ApiInfo(
                //标题
                "zmt的Swagger Api文档",
                //描述
                "作者描述",
                //版本
                "1.0",
                //服务条款url
                "https://www.baidu.com",
                //作者信息
                new Contact("zzz", "https://www.baidu.com", "123@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

重启项目，访问http://localhost:8080/swagger-ui/，看下效果

构建Docket时通过select()方法配置如何扫描接口

@Bean
public Docket docket(){
    return new Docket(documentationType.OAS_30)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors 配置要扫描接口的方式
        //basePackage 指定要扫描的包
        .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //建造者模式
        .build();
}

重启项目测试，发现只扫描了指定包下的接口

除了通过包 路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式

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

还可以配置接口扫描过滤

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){

    return new Docket(documentationType.OAS_30)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors 配置要扫描接口的方式
        //basePackage 指定要扫描的包
        .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //过滤什么路径，只扫描以/zzz开头的接口路径
        .paths(PathSelectors.ant("/zzz/**"))
        //建造者模式
        .build();
}

可选值有

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

通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器种访问

@Bean
public Docket docket(){
    return new Docket(documentationType.OAS_30)
        .apiInfo(apiInfo())
        //是否启用swagger
        .enable(false)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //.paths(PathSelectors.ant("/zzz/**"))
        .build();
}

重启项目，可以看到无法浏览器访问swagger

如何动态配置，当项目处于dev测试环境时显示swagger，处于pro发布环境时不显示swagger

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){

    //找对包org.springframework.core.env.Profiles;
    //设置要显示的swagger环境
    Profiles profiles = Profiles.of("dev","test");
    //获取项目运行环境
    //通过environment.acceptsProfiles(profiles)，判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(documentationType.OAS_30)
        .apiInfo(apiInfo())
        //实现动态配置swagger
        .enable(flag)
        .select()     .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
        //.paths(PathSelectors.ant("/zzz/**"))
        .build();
}

可以在项目种增加配置文件

#dev测试环境
server.port=8081

#pro生产环境
server.port=8082

#配置哪个环境生效
spring.profiles.active=dev

重启测试，启用dev配置文件时，可以访问swagger；启动pro配置文件时，不能访问swagger 25.7 配置API分组

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

public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){
		...
            
        return new Docket(documentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("zzz")
        ...
    }

重启项目查看分组

在SwaggerConfig中配置多个docket()方法就可以配置多个分组

@Bean
public Docket docket1(){
    return new Docket(documentationType.OAS_30).groupName("group1");
}
@Bean
public Docket docket2(){
    return new Docket(documentationType.OAS_30).groupName("group2");
}
@Bean
public Docket docket3(){
    return new Docket(documentationType.OAS_30).groupName("group3");
}

重启项目即可查看

新建一个实体类

public class User {
    public String username;
    public String password;
}

只要这个实体在请求接口的返回值上，都能映射到实体项中在HelloController类中写user()方法

//只要接口返回值中存在实体类，该实体类就会被扫描到swagger中
@PostMapping(value = "/user")
public User user(){
    return new User();
}

重启测试

还可以给实体类加文档注释

//给实体类加文档注释
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

重启测试

不是因为加了注解，才让实体类显示在swagger中，而是在接口方法的返回值上出现的实体类才会显示在swagger中。上面的注解只是为了实体类增加注释的也可以给接口配置一些注释

@RestController
public class HelloController {

    @ApiOperation("Hello控制接口")
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    //只要接口返回值中存在实体类，该实体类就会被扫描到swagger中
    @ApiOperation("User控制接口")
    @PostMapping(value = "/user")
    public User user(@ApiParam("用户") User user){
        return user;
    }
}

重启测试

Swagger的所有注解定义在io.swagger.annotations包下

swagger可以用来测试接口

输入测试的用户名密码

会显示测试接口的结果

Swagger可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读

接口文档实时更新，可以在线测试

相较于传统的Postman或Curl方式测试接口，使用swagger是傻瓜式操作，不需要额外说明文档，不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本不需要人为操作

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。

在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时的内存