摘要

公司前后端分离的项目，后端是采用的Swagger来进行测试的。挺好上手的，碰到问题，百度也能找到很多解决办法。

还是感觉有必要系统地学习一下。

正文

一、前后端分离

一开始的网站，前端只需要管理静态页面，后端通过模板引擎比如jsp来渲染数据。

前后端分离，目前最主流的技术栈是Vue+SpringBoot

前端：控制层、视图层

  • 前端工程化：伪造后端数据，如json。也就是说不需要后端，前端工程依旧能跑起来。

后端：控制层、服务层、数据访问层

前后端分离优点

  1. 相对独立、低耦合，仅通过API进行交互
  2. 前后端可以部署在不同服务器

前后端分离问题

  1. 前后端集成联调，前端开发和后端开发无法做到及时协商，尽早解决，最终会导致问题集中。

解决方案

  1. 制定schema计划，实时更新最新API，降低集成风险
  2. 前后端未分离时，word文档
  3. 前后端分离，需要前端测试接口，后端提供接口，这就需要Swagger了。

二、Springboot集成Swagger

swagger号称世界上最流行的api框架，RestFul Api文档在线自动生成工具，api文档与api定义同步更新，并且可以在线测试接口，支持多种语言。

swagger3.0参考文章

项目中使用Swagger需要springbox的jar包，里面包含

  1. swagger2
  2. ui

Springboot集成Swagger步骤

  1. 新建springboot-web项目
  2. 导入依赖
  3. 配置swagger

SpringBoot引用swagger3只需要导入以下

xml 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

SwaggerConfig

java 
1
2
3

@Configuration
public class SwaggerConfig {
}

HaloSwagger

java 
1
2
3
4
5
6
7

@RestController
public class HaloSwagger {
    @GetMapping("/halo")
    public String halo(){
        return "halo wode";
    }
}

访问http://localhost:8080/swagger-ui/index.html

1.png

三、配置Swagger信息

也很简单

java 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

@Configuration
public class SwaggerConfig {
    //配置swagger的实例
    @Bean
    public Docket docket(Environment environment) {
        Profiles profiles=Profiles.of("dev");
        //获取项目环境
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                /**
                 * apis():配置扫描的包，可选有配置基本包、any、none、带有注解的包
                 * withClassAnnotation显示包含Api注解的，如果不加这个，会有basic-error-controller显示
                 */
                //.apis(RequestHandlerSelectors.basePackage("top.meethigher.swagger.controller"))
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                /**
                 * 过滤路径
                 */
                .paths(PathSelectors.ant("/controller/**"))
                .build();
    }

    //配置swagger信息
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Swagger Api文档",
                "代码改变世界！",
                "1.0",
                "https://localhost:8080/swagger-ui/index.html",
                new Contact("meethigher", "https://meethigher.top", "meethigher@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

application.properties

properties 
1

spring.profiles.active=dev

application-dev.yml

yml 
1
2

server:
  port: 8080

application-prod.yml

yml 
1
2

server:
  port: 8080

四、分组

配置多个Docket即可

java 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

@Configuration
public class SwaggerConfig {
    //配置swagger的实例
    @Bean
    public Docket docket1(Environment environment) {
        Profiles profiles=Profiles.of("dev");
        //获取项目环境
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("呵呵")
                .enable(flag);
    }
    //配置swagger的实例
    @Bean
    public Docket docket(Environment environment) {
        Profiles profiles=Profiles.of("dev");
        //获取项目环境
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("哈哈")
                .enable(flag);
    }

    //配置swagger信息
    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Swagger Api文档",
                "代码改变世界！",
                "1.0",
                "https://localhost:8080/swagger-ui/index.html",
                new Contact("meethigher", "https://meethigher.top", "meethigher@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

五、实体类配置

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiModel：用对象来接收参数 ，修饰类

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@NotBlank/@NotNull：字段不能为空

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述，一般描述错误的响应

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiParam：单个参数描述

@ApiImplicitParam：一个请求参数，用在方法上

@ApiImplicitParams：多个请求参数