Swagger

前言：了解前后端分离

前后端分离
Vue + SpringBoot
后端时代：前端只用管理静态页面；html==>后端。模版引擎 JSP =>后端是主力
前后端分离式时代：

• 后端：后端控制层，服务层，数据访问层【后端团队】
• 前端：前端控制层，视图层【前端团队】
  – 伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来
• 前端后如何交互？ ===> API
• 前后端相对独立，松耦合。

产生了一个问题：前后端集成联调，前端人员和后端人员无法做到“即时协商，尽早解决”，最终导致问题集中爆发。
解决方案：

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

Swagger概述（overview）

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

Swagger官方

SpringBoot集成Swagger

依赖

        <!--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>

现在最新版本已经不是2.9.2，推荐使用这个的原因是其它高版本在SpringBoot中根本运行不了。

配置Swagger

使用JavaConfig的方式配置Swagger

package com.example.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    //enable是否启动Swagger
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                //RequestHandlerSelectors，配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                //paths()。扫描什么路径
                .paths(PathSelectors.ant("/kuang/**"))
                .build();
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("王思龙", "http://git.com//forget-the-dragon", "2405939934@qq.com");
        return new ApiInfo(
                "王思龙的SwaggerAPI文档",
                "没有描述",
                "v1.0",
                "http://www.baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

以上配置添加了
1.扫描接口
2.在多环境下判断是否使用Swagger
3.分组开发

Swagger接口注释

Controller注释

@Api(description = "Hello控制类")//给类添加注释
@RestController
public class HelloController {

    //@ApiOperation给接口方法添加注释,@ApiParam给接口参数添加注释
    @ApiOperation("Hello接口")
    @RequestMapping("/hello")
    public String hello(@ApiParam("用户名") String name){
        return "hello";
    }

    //只要我们的接口中，返回值存在实体类，就会扫描到Swagger中
    @RequestMapping("/user")
    public User user(){
        return new User();
    }
}

Model注释

@ApiModel("用户实体类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @ApiModelProperty("编号")
    private Long id;
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private Integer age;
}

测试页面：http://localhost:8080/swagger-ui.html

总结：
1.我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
2.接口文档实时更新
3.可以在线测试
【注意点】在正式发布的时候，关闭Swagger！！！出于安全考虑。而且节省运行的内存；