Swagger简单使用

Swagger

目标：

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

Swagger 简介

前后端分离

Vue + SpringBoot

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

前后端分离时代：

• 后端：后端控制层，服务层，数据访问层 【后端团队】

• 前端：前端控制层，视图层 【前端团队】

  • 伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够运行

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

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

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

产生一个问题：

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

解决方案：

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

Swagger

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

官网：https://swagger.io/

在项目使用Swagger需要 springbox;

• swagger2 （ swagger和swagger2 一个旧版一个新版的 ）
• ui

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、编写一个helloworld工程

4、配置Swagger ==> Config

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

接口：

@RestController
public class HelloController {

    // /error 算一个请求
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

5、测试运行，默认就有访问界面：http://localhost:8080/swagger-ui.html

配置Swagger

Swagger 的bean实例 Docket

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

    // 1. 配置了Swagger 的Docket的bean 实例
    @Bean
    public Docket docket(){
        // 链式操作
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置Swagger 信息 apiInfo
    private ApiInfo apiInfo(){
        // 作者信息
        Contact contact = new Contact("Reloss", "http://baidu.com", "111@qq.com");

        return new ApiInfo("Reloss Api Documentation",
                "Reloss 描述",
                "1.0",
                "http://baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

Swagger配置扫描接口

Docket.select ( )

// 1. 配置了Swagger 的Docket的bean 实例
@Bean
public Docket docket(){
    // 链式操作 是设计模式中的生产系列的建造者模式
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        // RequestHandlerSelectors，配置要扫描接口的方式
        // .basePackage(): 指定要扫描的包
        // .any(): 扫描全部
        // .none(): 都不扫描
        // .withClassAnnatation(): 扫描类上的注解，参数是一个注解的反射对象（带有的这些注解的类才加入）
        // .withMethodAnnatation(): 扫描方法上的注解
		.apis(RequestHandlerSelectors.basePackage("com.reloss.swagger.controller"))
        // .paths(): 过滤什么路径, 只有/reloss/** 下的路径才能访问
        .paths(PathSelectors.ant("/reloss/**"))
        .build();
}

配置是否启动Swagger

// 2. 配置了Swagger 的Docket的bean 实例
@Bean
public Docket docket(){
    // 链式操作 是设计模式中的生产系列的建造者模式
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        // 不启动Swagger  .enable() 是否启用Swagger， 如果false，则Swagger不能再浏览器中访问
        .enable(false)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.reloss.swagger.controller"))
        //.paths(PathSelectors.ant("/reloss/**"))
        .build();
}

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

• 判断是否是生产环境 flag = flase
• 注入 enable( flag )

// 2. 配置了Swagger 的Docket的bean 实例
@Bean
public Docket docket(Environment environment){

    // 获取项目的环境： ( 现在放在nacos上了，不使用这个方式了 )
    // 设置要显示的Swagger 环境
    Profiles profiles = Profiles.of("dev", "test");
    // 通过environment.acceptsProfiles()判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    // 链式操作 是设计模式中的生产系列的建造者模式
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("Reloss")
        // 不启动Swagger  .enable() 是否启用Swagger， 如果false，则Swagger不能再浏览器中访问
        .enable(flag)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.reloss.swagger.controller"))
        //.paths(PathSelectors.ant("/reloss/**"))
        .build();
}

配置API文档的 分组

.groupName("Reloss")

如何配置多个分组：多个Docket实例即可

// 3. 创建多个分组，扫描自己的写的接口
@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");
}

注解介绍

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似 @ApiModelProperty
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说 明”,hidden = true)	作用在类方法和属性上，hidden设置为true可 以隐藏该属性

实体类配置：

//@Api("注释")
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
    
    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }
    public String getPassword() {
        return password;
    }
    public void setPassword(String password) {
        this.password = password;
    }
}

Controller

// value 没用到
@Api(value = "类上注解Api", tags = "HelloController", description = "介绍 类上注解Api")
@RestController
public class HelloController {

    // /error 算一个请求
    @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 String postt(@ApiParam("方法参数上：用户名") User user){
        return "hello" + user.getUsername();
    }

    @ApiOperation(value = "value Post测试方法-参数字符串", notes = "notes Post测试方法-参数字符串")
    @PostMapping(value = "/postt1")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name = "username",value="str",dataType = "string")
            ,@ApiImplicitParam(paramType="query",name = "age",value="123",dataType = "int")})
    public String postt1(@ApiParam(value = "方法参数上：用户名", example = "reloss") String username, Integer age){
        System.out.println(username);
        return "hello " + username + " " + age;
    }
}

总结

1、可以通过Swagger给一些比较难理解的属性或者接口，增加注解信息

2、接口文档实时更新

3、可以在线测试

【注意点】在正式发布的时候，关闭Swagger！！！（ 安全，性能 ）