swagger简介

前后端分离

Vue+SpringBoot
后端时代：前端只用管理静态页面；html-->后端。模板引擎 jsp-->后端主力
前后端分离时代：

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

产生一个问题：

• 前后端集成联调，前端人员和后端人员无法做到“及时协商，今早解决”，最终导致问题集中爆发
  解决方案：
• 首先指定schema[计划的提纲]，实时更新最新API，降低集成的风险；
• 早些年：指定word文档
• 前后端分离：
• 前端测试后端接口：postman
• 后端提供接口，需要实时更新最新的消息及改动！

swagger

• 号称世界最流行的API框架；
• RestFul API 文档在线自动生成工具-->API文档与API定义同步更新
• 直接运行，可在线测试API接口
• 支持多种语言：Java、PHP...
  官网
  在项目中使用Swagger需要springfox；
• 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程序

@Controller
public class HelloController {
  @RequestMapping("/hello")
  @ResponseBody
  public String hello() {
    return "Hello";
  }
}

4. 配置Swagger-->config

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

5. 测试运行
   访问：http://localhost:8080/swagger-ui.html
   图片.png

配置Swagger信息

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 // 开启swagger2
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("赵毅梵", "https://www.jianshu.com/u/26ca55d16ca9", "1184546287@QQ.com");
    return new ApiInfo("赵毅梵的SwaggerApi文档", "云鱼科技", "1.0", "https://www.jianshu.com/u/26ca55d16ca9", contact, "Apache 2.0", "www.baidu.com", new ArrayList());
  }
}

Swagger配置扫描接口

Docket.select();

// 配置了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("com.zhao.swagger.controller"))
      // paths() 过滤什么路径
      .paths(PathSelectors.ant("/zhao/**")).build();
}

配置是否启动Swagger

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

应用题

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

• 判断是不是生产环境 flag=false
• 注入enable（flag）

application.properties

spring.profiles.active=pro

application-dev.properties

server.port=8082

application.properties

server.port=8081

SwaggerConfig

// 配置了Swagger的Docket的bean实例
    @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是否启动Swagger，如果为false，则Swagger不能在浏览中访问
                .enable(flag).select().apis(RequestHandlerSelectors.basePackage("com.zhao.swagger.controller"))
                // .paths(PathSelectors.ant("/zhao/**"))
                .build();
    }

配置API文档的分组

.groupName("...")

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

@Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("赵");
    }

    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("毅");
    }

    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("梵");
    }

配置实体类

// 给实体类添加注解，相当于给实体类增加注释信息
@ApiModel("用户实体类")
public class User {
    // 给字段添加注解，相当于是给字段增加注释信息
    @ApiModelProperty("用户id")
    public Integer id;
    @ApiModelProperty("用户名")
    public String Username;
}

实体类

@Controller
public class HelloController {
  // 只要接口中返回值中存在实体类，就会被扫描到Swagger中
  @PostMapping("user")
  public User user() {
    return new User();
  }

  // Operation接口，不是放在类上的，是方法
  @ApiOperation("用户名方法")
  @GetMapping("hello1")
  public String hello1(@ApiParam("用户名") String username) {
    return "用户名：" + username;
  }
}

方法

总结

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