Swagger

Swagger

学习目标：

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

一、Swagger简介

前后端分离：

Vue+SpringBoot

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

前后端分离时代：

• 后端：后端控制层，服务层，数据访问层

• 前端：前端控制层，视图层，伪造后端数据，json，已经存在了，不需要后端，前端工程依旧能跑起来

• 前后端如何交互？==>API接口

• 前后端相对独立，松耦合

• 前后端甚至可以部署在不同服务器上

产生一个问题：

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

解决方法：

• 首先指定一个Schema，实时更新最新API，降低集成风险
• 早些年指定world计划文档
• 前后端分离：前端测试后端接口：postman，后端提供接口，需要试试更新最新的消息及改动

swagger号称世界上最流行的API框架，优点：

• RestFul API文档在线自动生成工具==>API文档与API定义同步更新

• 直接运行，可以在线测试API接口

• 支持多种语言（JAVA，PHP）

• 官网：https://swagger.io/

在项目中使用Swagger需要导入jar包

• swagger2
• ui

二、SpringBoot集成Swagger

1、新建一个SpringBoot-Web项目

2、导入相关依赖

<!-- 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>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

3、编写一个Hello工程

4、配置Swagger==>config

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

5、测试运行：http://localhost:8080/swagger-ui.html

三、配置Swagger

Swagger的bean实例Docket

@Configuration
@EnableSwagger2//开启Swagger
public class SwaggerConfig {
    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置Swagger信息=apiinfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("aurora", "http://www.baidu.com", "706915503@qq.com");
        return new ApiInfo("aurora的SwaggerAPI文档",
                "极光永恒", "1.0",
                "http://www.baidu.com", contact, "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

四、Swagger配置扫描接口

Docket.select()

    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.aurora.swagger.controller"))
                .paths(PathSelectors.ant("/aurora/**"))
                .build();//RequestHandlerSelectors配置要扫描的包;basePackage指定要扫描的包；build
                        //withClassAnnotation扫描类上的注解，参数是注解的反射对象；withMethodAnnotation扫描方法上的注解
    }

配置是否启动Swagger

.enable(false)

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

• 判断是不是生产环境
• 注入enable（）；

//配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles of = Profiles.of("dev","test");
        //获取项目环境，通过 environment.acceptsProfiles(of)判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.aurora.swagger.controller"))
                //.paths(PathSelectors.ant("/aurora/**"))
                .build();//RequestHandlerSelectors配置要扫描的包;basePackage指定要扫描的包；build
                        //withClassAnnotation扫描类上的注解，参数是注解的反射对象；withMethodAnnotation扫描方法上的注解
    }

配置API文档分组

.groupName("aurora")

如何配置多个组

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

实体类配置

//@Api注释@ApiModel("用户实体类")public class User {    @ApiModelProperty("用户名")    public String username;    public String password;}

@RestControllerpublic class HelloController {    @GetMapping("/hello")    public String Hello(){        return "hello";    }    //只要我们的接口中返回值存在实体类，他就会被扫描到Swagger中    @PostMapping("/user")    public User user(){        return new User();    }}

//Operation接口不是放在类上而是在方法上@ApiOperation("Hello控制类")@GetMapping("/hello2")public String Hello2(@ApiParam("用户名") String username){    return "hello";}

总结：

我们可以通过Swagger给一些比较难理解的属性接口，增加注释信息

接口文档实时更新

可以在线测试

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

注意点：正式发布时，关闭Swagger，处于安全考虑，而且节省内存