Swagger

学习目标：

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

1、Swagger简介

前后端分离

Vue+SpringBoot

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

前后端分离时代：

• 后端：后端控制层，服务层，数据访问层
• 前端：前端控制层，视图层
• 前后端如何交互？==>API
• 前后端相对独立，松耦合；
• 前后端甚至可以部署在不同的服务器中

产生一个问题：

• 前后端集成联调，前端人员和后端人员无法做到，及时协商，尽早解决

解决方案：

• 首先指定schema【（计划或理论的）提要，纲要】，实时更新最新API，降低集成的风险

• 早些年：指定word计划文档

• 前后端分离：

  • 前端测试后端接口：postman
  • 后端提供接口，需要实时更新最新的消息及改动

2、Swagger

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

官网https://swagger.io

在项目使用Swagger需要springfox；

• swager2
• swagerUI

3、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>
   

   如果版本不匹配，在yaml中配置

   spring:
     mvc:
      pathmatch:
       matching-strategy: ant_path_matcher
   

3. 编写一个hello工程

4. 配置Swagger的Config

   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   
   }
   

   

4、配置Swagger

Swagger的bean实例Docket

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的docket的bean实例
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置Swagger信息Info
    private ApiInfo apiInfo(){
        Contact contact = new Contact("XS","http://localhost:8080/swagger-ui.html#/","[email protected]");
        return new ApiInfo(
                "XS的测试API文档",
                "Api Documentation",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

5、Swagger配置扫描接口

Docket.select（）

• RequestHandlerSelectors,配置要扫描的接口方式
• basePackage:指定要扫描的包
• any（）：扫面全部
• none（）：不扫描
• withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
• withMethodAnnotation：扫描方法上的注解

//配置了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.controller"))
            //选择路径扫描,
            // .paths(PathSelectors.ant(""))
            .build();
}

Docket.enable

是否启动swagger

   //配置了Swagger的docket的bean实例
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//不启动
    }

根据开发环境配置是否启动swager

如在测试环境中

spring:
  mvc:
   pathmatch:
    matching-strategy: ant_path_matcher
  profiles:
    active: dev

@Bean
public Docket docket(Environment environment){

    //设置要显示的swagger环境
    Profiles profiles = Profiles.of("dev");

    //获取项目的环境，通过environment.acceptsProfiles判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);
    return  new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.controller"))
            .build();
}

配置API文档的分组

Docket.groupName

配置多个分组就创建多个Docket对象

配置实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
//@api（）注释
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名属性")
    private String username;
    @ApiModelProperty("密码属性")
    private String password;
}

重写controller

@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    //只要我们的接口中，返回值存在实体类，它就会被扫描到swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
    //Operation接口
    @GetMapping("hello2")
    @ApiOperation("Hello控制类")
    public String hello(@ApiParam("用户名") String username){
        return  "hello"+username;
    }
}

6、总结：

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

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

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