SpringBoot - Swagger - 《Java 后端自学之路》

Swagger简介
Swagger
SpringBoot集成Swagger
配置Swagger
Swagger配置扫描接口

学习目标：

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

Swagger简介

前后端分离

Vue + SpringBoot

后端时代:前端只用管理静态页面; html==>后端。模板引擎JSP =>后端是主力

前后端分离式时代：

后端：后端控制层，服务层，数据访问层【后端团队】
前端：前端控制层，视图层【前端团队】
- 伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来。
前端后如何交互? ===> API
前后端相对独立，松耦合；
前后端甚至可以部署在不同的服务器上；

产生一个问题：

前后端集成联调，前端人员和后端人员无法做到“即使协商，尽早解决”，最终导致问题集中爆发；

解决方案：

首先指定schema[计划的提纲]，实时更新最新API，降低集成的风险；
早些年：指定word计划文档；
前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动！

Swagger

号称世界上最流行的Api框架；
RestFul Api文档在线自动生成工具 =>Api文档与Api同步更新；
直接运行，可以在线测试API接口；
支持多种语言：（Java，……）；

官网：https://swagger.io/

在项目使用Swagger需要springbox；

Swagger2
UI

SpringBoot集成Swagger

新建一个SpringBoot web项目；
导入相关依赖；```xml

io.springfox springfox-swagger2 2.9.2

io.springfox springfox-swagger-ui 2.9.2 ```
编写一个Hello工程；
配置Swagger；

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {
}

测试运行http://localhost:8080/swagger-ui.html；
开始导入的是version为3.0的，报错；降低为2.9.2后解决；

Swagger - 图1

如果使用的是swagger 3.0，就需要使用

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

访问：http://localhost:8080/swagger-ui/index.html 就可以实现swagger-ui.html的访问

配置Swagger

Swagger的Bean实例Docket；

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo());
}
//配置Swagger信息=apiInfo
private ApiInfo apiInfo(){
    //作者信息
    Contact contact = new Contact("6b92d6", "https://www.cnblogs.com/dafran/", "1412148742@qq.com");
    return new ApiInfo(
            "6b92d6的Swagger的Api文档",
            "Api Documentation",
            "v1.0",
            "https://www.cnblogs.com/dafran/",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
}

Swagger配置扫描接口

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors,配置要扫描接口的方式
            //basePackage:指定要扫描的包
            //any():扫描全部
            //none():不扫描
            //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
            //withMethodAnnotation:扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("cn.dafran.swagger"))
            //path, 过滤路径
            .paths(PathSelectors.ant("/dafran/**"))
            .build();
}

配置中是否启用Swagge

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //enable是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
           .enable(false)
            .select()
            .apis(RequestHandlerSelectors.basePackage("cn.dafran.swagger"))
            .build();
}

只希望Swagger在生产环境中使用，在发布的时候不使用

判断是不是生产环境flag = false
注入enable (flag)```java //设置要显示的Swagger环境 Profiles profiles = Profiles.of(“dev”, “test”); //通过environment.acceptsProfiles判晰是否处在自己设定的环境当中 boolean flag = environment.acceptsProfiles(profiles);

return new Docket(DocumentationType.SWAGGER_2)
```
      .apiInfo(apiInfo())
      //enable是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
      .enable(flag)
      .select()         
      .apis(RequestHandlerSelectors.basePackage("cn.dafran.swagger"))
      .build();
```
} ```

配置API文档分组

.groupName("6b92d6")

如何创建多个分组

@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");
}

实体类配置

Entity

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api("注释")
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

Controller

@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
    //只要我们的接口中,返回值中存在实体类,他就会被扫描到swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
    //Operation ——> 行动，接口
    @ApiOperation("Hello")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }
    @ApiOperation("Post测试")
    @PostMapping(value = "/postt")
    public User postt(@ApiParam("用户") User user){   
        return user;
    }
}

总结：

我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
接口文档实时更新
可以在线测试

Swagger是一个优秀的工具，几乎所有大公司都有使用它

【注意点】在正式发布的时候，关闭Swagger。出于安全考虑。而且节省运行的内存;