Swagger入门到精通-比贝网

学习目标：

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

Swagger简介

前后端分离

Vue + SpringBoot

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

前后端分离时代：

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

产生一个问题：

前后端集成联调，前端人员和后端人员无法做到"即使协商，尽早解决"，最后导致问题集中爆发；

解决方案：

首先指定schema[计划的提纲]，实时更新最新API，降低集成的风险
早些年：指定word计划文档
前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更细最新的消息及改动

Swagger

号称世界上最流行的Api框架
RestFul Api 文档在线自动生成工具 => Api文档与API定义同步更新
直接运行，可以在线测试API接口
支持多种需要：Java、PHP.....

官网：https://swagger.io

在项目中使用Swagger需要Springbox

swagger2
swagger-ui

SpringBoot 集成 Swagger3

注意：swagger2和swagger3在前面配置有较大区别，后面几乎一样，3功能更多更好，所以就不写2教程了

新建一个SpringBoot Web项目

导入相关依赖


io.springfox
   springfox-boot-starter
   3.0.0

编写一个工程

配置Swagger ==> Config

@Configuration
@EnableOpenApi
public class SwaggerConfig {

}

测试运行：http://localhost:8001/swagger-ui/index.html

配置Swagger信息

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    /**
     * 配置swagger的Docker的bean实例
     * @return docket
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
    }

    /**
     * 配置Swagger信息apiInfo
     * ApiInfo 作者消息
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("FlamingYouth", "https://www.bigbey.com", "yf935917439@gmail.com");
        return new ApiInfo(
                "FlamingYouth的Swagger接口管理工具",
                "我从来不梦想,我只是努力的认清事实",
                "v1.0",
                "https://www.bigbey.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

Swangger配置扫描接口

Docker.select()

public Docket docket() {
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
         .select()
         // .apis(RequestHandlerSelectors.any()) // 不扫描
         // .apis(RequestHandlerSelectors.none()) // 扫描全部(默认)
         // .apis(RequestHandlerSelectors.withClassAnnotation()) // 扫描类上的注解,参数是一个注解的反射对象
         // .apis(RequestHandlerSelectors.withMethodAnnotation())// 扫描方法上的注解
         .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
         // .paths() 过滤器 只扫描flaming下的接口
         .paths(PathSelectors.ant("/flaming/**"))
         .build();
}

配置是否启动Swagger

Docker.enable()

public Docket docket() {
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
         .enable(false) // 是否启动swagger,(默认为true) 建议线上默认关掉
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
         .build();
}

扩展：利用YML直接实现代码与配置分离

application.yml

spring:
  profiles:
    active: dev

application-dev.yml

spring:
  application:
    name: springfox-swagger
server:
  port: 8080
# ===== 自定义swagger配置 ===== #
swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: v1.0
  application-description: springfox swagger 3.0整合Demo
  try-host: http://localhost:${server.port}
  apis: "com.swagger.controller"

application-pro.yml

spring:
  application:
    name: springfox-swagger
server:
  port: 8080
# ===== 自定义swagger配置 ===== #
swagger:
  enable: false
  application-name: ${spring.application.name}
  application-version: v1.0
  application-description: springfox swagger 3.0整合Demo
  try-host: http://localhost:${server.port}
  apis: "com.swagger.controller"

SwaggerProperties实体类

@Data
@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties {
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
     */
    private Boolean enable;

    /**
     * 项目应用名
     */
    private String applicationName;

    /**
     * 项目版本信息
     */
    private String applicationVersion;

    /**
     * 项目描述信息
     */
    private String applicationDescription;

    /**
     * 接口调试地址
     */
    private String tryHost;

    /**
     * 扫描地址
     */
    private String apis;
}

SwaggerConfig

package com.swagger.config;

import com.swagger.entity.SwaggerProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;

/**
 * Swagger配置
 *
 * @program: swagger
 * @author: FlamingYouth
 * @create: 2021-05-27 22:21
 **/
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    private final SwaggerProperties swaggerProperties;

    public SwaggerConfig(SwaggerProperties swaggerProperties) {
        this.swaggerProperties = swaggerProperties;
    }

    /**
     * 配置swagger的Docker的bean实例
     * @return docket
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .enable(swaggerProperties.getEnable())
                .apiInfo(apiInfo())
                .host(swaggerProperties.getTryHost())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApis()))
                .build();
    }

    /**
     * 配置Swagger信息apiInfo
     * ApiInfo 作者消息
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        // 自己可以定义，照葫芦画瓢
    }
}

配置API分组

.groupName("FlamingYouth")

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

    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.OAS_30)
                .enable(swaggerProperties.getEnable())
                .apiInfo(apiInfo())
                .host(swaggerProperties.getTryHost())
                .groupName("A")
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApis()))
                .build();
    }
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.OAS_30)
                .enable(swaggerProperties.getEnable())
                .apiInfo(apiInfo())
                .host(swaggerProperties.getTryHost())
                .groupName("B")
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApis()))
                .build();
    }
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.OAS_30)
                .enable(swaggerProperties.getEnable())
                .apiInfo(apiInfo())
                .host(swaggerProperties.getTryHost())
                .groupName("C")
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApis()))
                .build();
    }

类的名称配置

实体类配置

/**
 * 用户实体类
 *
 * @program: swagger
 * @author: FlamingYouth
 * @create: 2021-05-28 00:27
 **/
@Data
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String userName;
    @ApiModelProperty("密码")
    private String passWorld;
}

控制层配置

/**
 * 控制层
 *
 * @program: swagger
 * @author: FlamingYouth
 * @create: 2021-05-27 23:01
 **/
@Api(tags = "Swagger测试")
@RestController
@RequestMapping("controller")
public class Controller {

    @ApiOperation(value = "Get无参测试")
    @GetMapping("/hello")
    public String hello() {
        return "你好";
    }

    @ApiOperation(value = "Post有参测试")
    @PostMapping("/User")
    public User user(User user) {
        return user;
    }

    @ApiOperation(value = "Get有参测试")
    @ApiImplicitParam(name = "para", value = "测试参数")
    @GetMapping("/helloPara")
    public String helloPara(String para){
        return para;
    }
}

多参设置

@PostMapping(value = "/login")
public User login(String userName, String passWorld) {
    User user = new User();
    user.setUserName(userName);
    user.setPassWorld(passWorld);
    return  user;
}

总结：

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

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

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

目录CONTENT

Swagger入门到精通