[Java知识库]Spring Boot（十五）--------Swagger介绍及集成

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

25、Swagger

25.1 前言

• 前后端分离：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版本之前

<!--2.9.2版本-->
<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>

• 3.0版本之后，springboot版本2.5.6

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

• 编写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页面

25.4 配置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/，看下效果

25.5 配置扫描接口

• 构建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<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> 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()控制

25.6 配置Swagger开关

• 通过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");
}

• 重启项目即可查看

25.8 实体类配置

• 新建一个实体类

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

• 重启测试

25.9 常用注解

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

25.10 Swagger测试接口

• swagger可以用来测试接口

• 输入测试的用户名密码

• 会显示测试接口的结果

25.11 小结

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

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

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

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

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