【Swagger】Swagger简介及简单使用

1.Swagger简介

1.1 前言

说起Swagger就不得不说前后端分离
当前最主流的前后端分离技术栈：Vue+Springboot

后端时代：
前端只用管理静态页面:html、css、js
最后统一交给后端，后端将其修改为jsp，在整个过程中，后端充当主力

前后端分离时代：
后端：后端控制层，服务层，数据访问层【后端团队】
前端：前端控制层，视图层【前端团队】
前端可以自定义一些伪后端数据：json,在写的时候就存在，不需要后端，前端工程依旧能够跑起来

那么前端后端如何交互？
此时可以考虑API

前后端分离好处：
前后端相对独立，松耦合
前后端设置可以部署在不同的服务器上

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

解决方式：
首先指定schema[提纲（计划的提纲）]，实时更新最新的API，降低集成风险
早期：指定word计划文档
前后端分离时期：
前端测试后端接口：一些API测试工具（例如postman）
后端提供接口，需要实时更新最新的消息及改动

2、Swagger简介

Swagger号称世界上最流行的Api框架
RestFul Api 文档在线自动生成工具，Api文档与Api定义同步更新
直接运行，可以在线测试API接口

支持多种语言

官网：http://swagger.io/

2.Swagger简单使用

2.1 Springboot集成Swagger

SpringBoot集成Swagger => springfox，两个jar包

• Springfox-swagger2
• springfox-swagger-ui

使用Swagger

要求：jdk 1.8 +， 否则swagger2无法运行

步骤：

1. 新建一个SpringBoot-web项目
2. 添加Maven依赖

<dependency>
   <groupId>io.springfoxgroupId>
   <artifactId>springfox-swagger2artifactId>
   <version>2.9.2version>
dependency>

<dependency>
   <groupId>io.springfoxgroupId>
   <artifactId>springfox-swagger-uiartifactId>
   <version>2.9.2version>
dependency>

3. 编写HelloController，测试确保运行成功！
4. 要使用Swagger，需要编写一个配置类SwaggerConfig来配置 Swagger

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

5. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面

2.2 配置Swagger

1. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger。

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

2. 可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger", // 标题
           "Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

3. Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

重启项目后，配置生效

2.3 配置扫描接口

1. 构建Docket时通过select()方法配置怎么扫描接口

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
      .build();
}

2. 重启项目测试，由于配置根据包的路径扫描接口，只能看到相应包小的接口
3. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口

basePackage(final String basePackage) // 根据包路径扫描接口
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)

4. 除此之外，还可以配置接口扫描过滤

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/path开头的接口
      .paths(PathSelectors.ant("/path/**"))
      .build();
}

5. 这里的可选值还有如下

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

2.4 配置Swagger开关

1. 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
      .paths(PathSelectors.ant("/path/**"))
      .build();
}

2. 动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean b = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
      .paths(PathSelectors.ant("/path/**"))
      .build();
}

3. 可以在项目中增加配置文件

   不同环境可使用不同的配置文件

2.5 配置API分组

1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组

@Bean
public Docket docket(Environment environment) {   
	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("test1") // 配置分组
	// ······
}

2. 重启项目即可查看分组
3. 配置多个分组只需要配置多个docket即可

@Bean
public Docket docket1(){
	return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
	return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
	return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

4. 重启项目即生效

2.6 实体配置

1. 新建一个实体类

//@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;
    }
}

2. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中

@RestController
public class HelloController {

    //   /error默认错误请求
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

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

3. 重启即会生效

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

• @ApiModel为类添加注释
• @ApiModelProperty为类属性添加注释

总结：

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

【注意点】：在正式发布的时候，关闭Swagger！！！

• 出于安全考虑
• 而且节省内存

2.7 常用注解

Swagger的所有注解定义在io.swagger.annotations包下