初步及理解使用Swagger

一、Swagger

• 号称世界上较流行的API框架
• RestFul API 文档在线自动生成工具 -> API文档与API同步更新
• 直接运行,可以在线测试API接口
• 支持多种语言,如:Java、PHP

什么是Swagger?

1. Swagger可以说是一种解决前后端分离的机制
2. 前端可以使用伪数据或mork进行交互
3. 前后端如何实现交互? -> API
4. 前后端相对独立,松耦合
5. 前后端可以部署在不同的服务器上

Swagger能够解决什么问题?

1. 首先如果前端人员与后端人员某个模块的字段不一致,不能进行实时更新?
   • 这个时候swagger指定一个schema[计划的大纲],实时更新的API,降低集成的风险

二、实战Swagger

使用SpringBoot集成Swagger

1. 新建一个SpringBoot - Web项目

2. 导入Swagger相关依赖

           <!-- 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工程 -> 控制器 Controller-<

   package cn.qj.cnmrli.swagger.controller;
   
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   /**
    * @author 青衿
    * @Date 2021/2/9 19:00
    **/
   @RestController
   public class HelloController {
   
       @RequestMapping(value = "/hello")
       public String hello() {
           return "hello";
       }
   }
   

4. 编写一个Swagger配置类 -> Config -<

   package cn.qj.cnmrli.swagger.config;
   
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   /**
    * @author 青衿
    * @Date 2021/2/9 19:05
    **/
   @Configuration
   
   //TODO 开始swagger2
   @EnableSwagger2
   public class SwaggerConfig {
   }
   

5. 启动测试Swagger

   http://localhost:8080/swagger-ui.html#/hello-controller

三、配置Swagger

Swagger的bean实例Docket;

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

//TODO 配置Swagger信息 => apiInfo
    private ApiInfo apiInfo() {

        //TODO 作者信息
        Contact contact = new Contact("青衿", "https://blog.csdn.net/", "CnMrLi@163.com");

        return new ApiInfo(
                "粒桃的SwaggerAPI文档", //标题
                "努力的搬运工", //标注
                "v1.0", //版本
                "https://blog.csdn.net/",//服务地址
                contact, //著名、地址、邮箱
                "Apache 2.0", //开源版本号
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }

四、Swagger配置扫描接口

Docket.select()

//TODO 配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //TODO RequestHandlerSelectors,配置要扫描接口的方式
                //TODO basePackage():指定扫描的包
                //TODO any():扫描全部
                //TODO none():不扫描
                //TODO withClassAnnotation(RestController.class):扫描类上的注解,参数是一个注解的反射对象
                //TODO withMethodAnnotation(GetMapping.class):扫描方法上的注解,参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("cn.qj.cnmrli.swagger.controller"))
                //paths():过滤什么路径
                .paths(PathSelectors.ant("/qj/**"))
                .build();
    }

五、配置是否启动Swagger

//TODO 配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //TODO enable(false):是否启用Swagger,false为禁用,默认为true启用,则Swagger不能在浏览器中访问
                .enable(false)
                .select()
                //TODO RequestHandlerSelectors,配置要扫描接口的方式
                //TODO basePackage():指定扫描的包
                //TODO any():扫描全部
                //TODO none():不扫描
                //TODO withClassAnnotation(RestController.class):扫描类上的注解,参数是一个注解的反射对象
                //TODO withMethodAnnotation(GetMapping.class):扫描方法上的注解,参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("cn.qj.cnmrli.swagger.controller"))
                //paths():过滤什么路径
//                .paths(PathSelectors.ant("/qj/**"))
                .build();
    }

六、题外题:

如何保证Swagger在生产中使用,发布后不使用?

• flag=false 判断是不是生产环境
• 注入enable(flag)

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

        //TODO Profiles.of("dev","test"):设置要显示的Swagger的环境
        Profiles profiles = Profiles.of("dev", "test");

        //TODO 获取项目中的环境如:生产环境、开发环境
        //TODO getActiveProfiles():获得一个激活文件
        //TODO getDefaultProfiles():获得一个默认文件
        //TODO acceptsProfiles():监听一个对象
        //environment.acceptsProfiles(profiles):判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //TODO enable(false):是否启用Swagger,false为禁用,默认为true启用,则Swagger不能在浏览器中访问
                .enable(flag)
                .select()
                //TODO RequestHandlerSelectors,配置要扫描接口的方式
                //TODO basePackage():指定扫描的包
                //TODO any():扫描全部
                //TODO none():不扫描
                //TODO withClassAnnotation(RestController.class):扫描类上的注解,参数是一个注解的反射对象
                //TODO withMethodAnnotation(GetMapping.class):扫描方法上的注解,参数是一个注解的反射对象
                .apis(RequestHandlerSelectors.basePackage("cn.qj.cnmrli.swagger.controller"))
                //TODO paths():过滤什么路径
//                .paths(PathSelectors.ant("/qj/**"))
                .build();
    }

如何配置Swagger分组与多个分组?

• groupName("粒桃")
  

配置多个分组,多实现几个Docket

@Bean
    public Docket docketXiaoBai() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小白");
    }

    @Bean
    public Docket docketXiaoHei() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小黑");
    }

    @Bean
    public Docket docketXiaoLan() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小蓝");
    }

    @Bean
    public Docket docketXiaoLv() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("程序猿小绿");
    }

七、实体类

pojo实体类

package cn.qj.cnmrli.swagger.pojo;

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

/**
 * @author 青衿
 * @Date 2021/2/9 21:38
 **/
//@Api(注释信息)
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String password;
}

Controller控制体

package cn.qj.cnmrli.swagger.controller;

import cn.qj.cnmrli.swagger.pojo.User;
import io.swagger.annotations.Api;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 青衿
 * @Date 2021/2/9 19:00
 **/

@RestController
@Api(tags = "Hello控制器")
public class HelloController {

    //Operation接口,是在方法上加上注释
    @ApiOperation("Hello控制器")
    @GetMapping(value = "/hello")
    public String hello() {
        return "hello";
    }

    //Operation接口,是在方法上加上注释
    @ApiOperation("user控制器")
    //TODO 只要我们的接口中,返回值中存在实体类,他就会被扫描到Swagger中
    @PostMapping(value = "/user")
    public User user() {
        return new User();
    }


    //Operation接口,是在方法上加上注释
    @ApiOperation("Hello2控制器")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username) {
        return "hello" + username;
    }

    //Operation接口,是在方法上加上注释
    @ApiOperation("Postt测试类")
    @PostMapping(value = "/postt")
    public User postt(@ApiParam("用户名") User user) {
        return user;
    }

}

八、总结

1. 可以通过Swagger给一些比较以及难理解的属性或接口,进行添加注释
2. 接口文档实时更新
3. 可以在线测试

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