Swagger-入门

1. 简介

Swagger是基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源接口文档自动生成工具，可以让开发人员快速设计、构建、记录以及使用 Rest API。

目前由2.0版本和3.0版本，2.0版本在2017年停止维护。

Swagger 主要包含了以下三个部分：

  • Swagger Editor：基于浏览器的编辑器，编写OpenAPI 规范。
  • Swagger UI：将编写的 OpenAPI 规范呈现为交互式的 API 文档。
  • Swagger Codegen：它可以通过为 OpenAPI规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

2. SpringFox

https://github.com/springfox/springfox

是 spring 社区维护的一个非官方项目，是一个开源的API Doc的框架，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。

SpringFox 3.0.0，支持Spring5，Webflux，支持OpenApi 3.0.3，有springboot的整合的starter，使用更便捷

3. 与springboot整合

  • 添加依赖
1
2
3
4
5
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
  • 添加配置类
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
package cn.aacopy.shop.common.config;

import org.springframework.context.annotation.Bean;
import org.springframework.http.HttpMethod;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

/**
 * @author cmyang
 * @date 2022/12/30 15:36
 */
@Component
@EnableOpenApi
public class SwaggerConfig {

    /**
     * 对C端用户的接口文档
     * @return
     */
    @Bean
    public Docket webApiDoc() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("用户端接口文档")
                .pathMapping("/")
                //定义是否开启Swagger，false是关闭，可以通过配置文件去控制，线上关闭
                .enable(true)
                //配置文档的元信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.aacopy.shop"))
                //正则匹配请求路径，并分配到当前项目组
                .paths(PathSelectors.ant("/api/**"))
                .build()
                // 新版SwaggerUI3.0
                .globalRequestParameters(globalRequestParameters())
                .globalResponses(HttpMethod.GET,getGlabalResponseMessage())
                .globalResponses(HttpMethod.POST,getGlabalResponseMessage());
    }

    /**
     * 可以定义多个
     * 对管理端的接口文档
     * @return
     */
    @Bean
    public Docket adminApiDoc() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("管理端接口文档")
                .pathMapping("/")
                //定义是否开启Swagger，false是关闭，可以通过变量去控制，线上关闭
                .enable(true)
                //配置文档的元信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.aacopy.shop"))
                //正则匹配请求路径，并分配到当前项目组
                .paths(PathSelectors.ant("/admin/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("cm-shop")
                .description("微服务接口文档")
                .contact(new Contact("cmyang", "https://aacopy.cn", "969312613@qq.com"))
                .version("v1.0")
                .build();
    }

    /**
     * 配置全局通用参数
     * @return
     */
    private List<RequestParameter> globalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("token")
                .description("登录令牌")
                .in(ParameterType.HEADER)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
//        parameters.add(new RequestParameterBuilder()
//                .name("token2")
//                .description("xx令牌")
//                .in(ParameterType.HEADER)
//                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
//                .required(false)
//                .build());
        return parameters;
    }

    /**
     * 生成通用的响应信息
     */
    private List<Response> getGlabalResponseMessage() {
        List<Response> list = new ArrayList<>();
        list.add(new ResponseBuilder()
                .code("4xx")
                .description("请求错误，根据code和msg检查")
                .build());
        return list;
    }
}

4. 使用注解

  • @Api 模块配置，用在controller类，描述API接口
1
2
@Api(tags = "用户模块")
public class UserController {}
  • @ApiOperation 接口配置，用在方法上，描述接口方法
1
2
@ApiOperation("保存用户信息")
public ResultData save(@RequestBody UserDTO userDTO) {}
  • @ApiParam 方法参数配置，用在入参上面，描述参数
1
2
3
@ApiOperation("删除用户")
@DeleteMapping("/delete/{id}")
public ResultData delete(@ApiParam(name = "用户id", required = true) @PathVariable String id) {}
  • @ApiIgnore 忽略此接口不生成文档
1
2
3
4
@ApiIgnore
@ApiOperation("删除用户")
@DeleteMapping("/delete/{id}")
public ResultData delete(@ApiParam(name = "用户id", required = true) @PathVariable String id) {}
  • @ApiModel表示对类进行说明，用于参数用实体类接收，value–表示对象名，description–描述
1
2
@ApiModel("用户对象")
public class UserDTO {
  • @ApiModelProperty用于方法，字段； 表示对model属性的说明或者数据操作更改
1
2
@ApiModelProperty(value = "姓名", required = true)
private String name;
  • 示例
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
38
39
40
41
42
@Api(tags = "用户模块")
@RestController
@RequestMapping("/api/v1/user")
public class UserController {

    @ApiOperation("保存用户")
    @PostMapping("/save")
    public ResultData save(@RequestBody UserDTO userDTO) {
        return ResultData.success();
    }

    @ApiOperation("删除用户")
    @DeleteMapping("/delete/{id}")
    public ResultData delete(@ApiParam(name = "用户id", required = true) @PathVariable String id) {
        return ResultData.success();
    }

    @ApiOperation("根据用户id查询用户")
    @GetMapping("/findUserById/{id}")
    public ResultData<UserVO> findUserById(@ApiParam(name = "用户id", required = true) @PathVariable String id) {
        return ResultData.success();
    }
}


@ApiModel("用户对象")
@Data
public class UserDTO {
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
}

@ApiModel("用户对象")
@Data
public class UserVO {
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
}

5. knife4j

5.1 简介

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

文档地址：https://doc.xiaominfo.com/

gitee: https://gitee.com/xiaoym/knife4j

5.2 不使用增强功能,纯粹换一个swagger的前端皮肤

不使用增强功能,纯粹换一个swagger的前端皮肤，这种情况是最简单的,你项目结构下无需变更

可以直接引用swagger-bootstrap-ui的最后一个版本1.9.6或者使用knife4j-spring-ui

老版本引用

1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

新版本引用

1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>${lastVersion}</version>
</dependency>

5.3 Spring Boot项目单体架构使用增强功能

在Spring Boot单体架构下,knife4j提供了starter供开发者快速使用

1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>

该包会引用所有的knife4j提供的资源，包括前端Ui的jar包

5.4 Spring Cloud微服务架构

在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter

1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-micro-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>

在网关聚合文档服务下,可以再把前端的ui资源引入

1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>

5.5 集成到项目里

  • 引入依赖
1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>3.0.3</version>
</dependency>

访问地址：http://127.0.0.1:8080/doc.html