粤嵌打卡第49天（一文带你学习项目集成工具Swagger）

项目集成工具 Swagger

1、Swagger简介

学习目标：

• 了解Swagger的概念及作用
• 掌握在项目中集成Swagger自动生成API文档

Swagger简介

前后端分离

• 前端 -> 前端控制层、视图层
• 后端 -> 后端控制层、服务层、数据访问层
• 前后端通过API进行交互
• 前后端相对独立且松耦合

产生的问题

• 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

• 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险

• 号称世界上最流行的流行框架

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

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

• 支持多种语言（java、PHP等）

  官网：https://swagger.io/

  在项目中如何使用swagger?

  项目中使用Swagger需要spingfox

  • swagger2 jar包

  • ui jar包

    2、SpringBoot 集成Swagger

    1、新建一个springboot =web项目

    2、导入相关jar包

    <!-- 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、创建一个Hello工程

    package com.baoji.swagger.controller;
    
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    public class swaggerController {
        @GetMapping("/hello")
        public String hello(){
            return "Hello！";
        }
    }
    

    4、定义配置config类(需要@Configuration和@EnableSwagger2注解)

package com.baoji.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration  //定义此类为配置文件
@EnableSwagger2  //定义开启swagger2
public class SwaggerConfig {
}

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

3、配置Swagger

在config类中，将swagger的docter实例注入到springboot，配置界面参数信息

package com.baoji.swagger.config;

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的docker的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    //配置swagger信息== apiInfo
    private ApiInfo apiInfo(){
        //配置作者的信息
       Contact contact = new Contact("张三", "https://gitee.com/Lmobject", "1042486377@qq.com");
        return new ApiInfo(
                "Lmobject的Swagger API文档",
                "机会总是留给有准备的人",
                "v1.0",
                "https://gitee.com/Lmobject",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

测试：http://localhost:8080/swagger-ui.html

4、Swagger配置扫描接口

Docket.select()

 //配置了swagger的docker的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors  配置要扫描的接口
                //basePackage    指定要扫描的包
                //any()  扫描全部
                //none()  不扫描
                //withClassAnnotation:  扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:  扫描方法上的注解
                //一般选择扫描包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.baoji.swagger.controller"))
                //paths()  过滤什么路径(一般不需要，只要扫描指定的包就行)
                //.paths(PathSelectors.ant("/baoji/**"))
                .build();
    }

5、配置是否启动swagger

enable() //enable是否启动swagger,如果为false,表示浏览器不能访问swagger

 //配置了swagger的docker的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable()  //enable是否启动swagger,如果为false,表示浏览器不能访问swagger
                .enable(false)
                .select()
                //RequestHandlerSelectors  配置要扫描的接口
                //basePackage    指定要扫描的包
                //any()  扫描全部
                //none()  不扫描
                //withClassAnnotation:  扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:  扫描方法上的注解
                //一般选择扫描包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.baoji.swagger.controller"))
                //paths()  过滤什么路径
                //.paths(PathSelectors.ant("/baoji/**"))
                .build();
    }

问题一： 如何让Swagger在生产环境中使用，在发布的时候不使用呢？

• 1、先判断是不是生产环境 flag=true

• 2、注入enable(flag)

  我们先来模拟配置下开发环境和发布环境

  application.properties配置文件中配置启动的环境

  spring.profiles.active=dev  #启动开发环境
  

  application-dev.properties配置开发环境的端口号

  server.port=8081
  

  application-pro.properties配置发布环境的端口号

  server.port=8082
  

  config中配置要设置显示的swagger环境、判断是否处于自己设定的环境（boolean值）、然后设置到enable中

  //配置了swagger的docker的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()  //enable是否启动swagger,如果为false,表示浏览器不能访问swagger
                  .enable(flag)
                  .select()
                  //RequestHandlerSelectors  配置要扫描的接口
                  //basePackage    指定要扫描的包
                  //any()  扫描全部
                  //none()  不扫描
                  //withClassAnnotation:  扫描类上的注解，参数是一个注解的反射对象
                  //withMethodAnnotation:  扫描方法上的注解
                  //一般选择扫描包下的接口
                  .apis(RequestHandlerSelectors.basePackage("com.baoji.swagger.controller"))
                  //paths()  过滤什么路径
                  //.paths(PathSelectors.ant("/baoji/**"))
                  .build();
      }
  

  测试: http://localhost:8081/swagger-ui.html

6、配置API文档的分组

 .groupName("Lmobject")

问题三：如何配置多个分组？

多个Docket实例即可

  //配置了swagger的docker的bean实例
    @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");
    }

7、配置实体类

实体类(3个对于API文档的注释)

package com.baoji.swagger.pojo;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

//@Api(注释)
@ApiModel("用户实体类")  //表示在返回的接口文档中标明此类含义
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

控制类（对于API文档的注释）

package com.baoji.swagger.controller;

import com.baoji.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = {"Index控制器"}) // tags是对Controller的接口重新分类
@RestController
public class swaggerController {
    //Operation 接口，用于放在方法上
    @ApiOperation("Hello控制类") //用于描述接口的注释
    @GetMapping("/hello")
    public String hello(@ApiParam("用户名") String name){
        return "Hello！"+name;
    }
    //只要我们的接口中,返回值存在实体类，它就会扫描到swaager中
    @GetMapping("/user")
    public User user(){
        return new User();
    }
    @PostMapping("/postTest")
    public User postTest(@ApiParam("用户实体类") User user){
        return user;
    }
}

8、测试功能

在对应的接口中点击Try it out

Excute 开始执行接口方法，完成之后，后面有对应的返回响应码

9、总结

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

2、接口文档实时更新

3、可以在线测试

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

「注意点」在正式发布的额时候，关闭Swagger！！！出于安全考虑，而且节省运行的内存；