Swagger

Swagger

学习目标：

• 了解Swagger的作用和概念
• 了解前后端分离
• 在SpringBoot中集成Swagger

Swagger简介

前后端分离

Vue + SpringBoot

• 前端 -> 前端控制层、视图层
• 后端 -> 后端控制层、服务层、数据访问层
• 前后端通过API进行交互
• 前后端相对独立且松耦合

产生的问题

• 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

• 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险

Swagger

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 直接运行，在线测试API
• 支持多种语言 （如：Java，PHP等）
• 官网：https://swagger.io/

SpringBoot集成Swagger

1. 新建一个SpringBoot = web项目
2. 导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

3. 编写一个Hello工程

4. 配置Swagger====>Config

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

5. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

以上是针对springboot2.6.x以下，swagger3.0以下

以下是针对springboot2.6.x以上，swagger3.0

1. 新建一个SpringBoot = web项目

2. 导入相关依赖

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter-->
           <dependency>
               <groupId>io.springfox</groupId>
               <artifactId>springfox-boot-starter</artifactId>
               <version>3.0.0</version>
           </dependency>
   

5. http://localhost:8080/swagger-ui/index.html，可以看到swagger的界面；

配置Swagger

Swagger的bean实例Docket;

Swagger配置扫描接口

Docket.select ()

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())

            .select()// 通过.select()方法，去配置扫描接口,
            // RequestHandlerSelectors配置如何扫描接口
            // any()  扫描所有，项目中的所有接口都会被扫描到
            // none() 不扫描接口
            // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
            //withMethodAnnotation(final Class<? extends Annotation> annotation)
            // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
            // withClassAnnotation(final Class<? extends Annotation> annotation)
            // asePackage(final String basePackage) // 根据包路径扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
            //paths() 过滤什么路径
            .paths(PathSelectors.ant("/kuang/**"))
            .build();
};

配置是否启动Swagger

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false) //enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
            //paths() 过滤什么路径
            //.paths(PathSelectors.ant("/kuang/**"))
            .build();
};

如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean b = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

配置API文档的分组

.groupName("狂神")

如何配置多个分组；多个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");
}

实体类配置

1、新建一个实体类

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

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

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

3、重启查看测试

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

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释