一、Swagger

1、Swagger 介绍

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

2、Swagger 的优势

  • 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
  • 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

3、Swagger 与 springfox-swagger2 的区别

  • Swagger 是一种规范。
  • springfox-swagger2 是基于 Spring 生态系统的该规范的实现。
  • springfox-swagger-ui 是对 swagger-ui 的封装，使其可以使用 Spring 的服务。

4、swagger2

swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它主要包含三部分：

  • swagger Codegen: 通过 Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。

  • swagger UI:提供了一个可视化的 UI 页面展示描述文件。可以做一些的接口请求。

  • swagger Editor: 编辑 swagger 描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

二、整合 Swagger2

使用的开发环境：

  • Spring Boot：2.2.1.RELEASE

  • JDK 8

  • swagger：2.9.2

1、pom 依赖

需要的依赖

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
<properties>
    <swagger.version>2.9.2</swagger.version>
    <swagger-bootstrap-ui.version>1.9.2</swagger-bootstrap-ui.version>
</properties>

<dependencyManagement>
    <dependencies>

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!--swagger ui 可视化依赖，如果不添加此依赖，测试的结果是json格式的数据-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!--swagger-bootstrap-ui 国人开发的ui包-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>${swagger-bootstrap-ui.version}</version>
        </dependency>

    </dependencies>
</dependencyManagement>

2、编写 Swagger2Config 配置文件

swagger 提供了一个 Docket 对象，我们可以灵活的配置 swagger 的各项属性

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
@Configuration // 表示这是一个配置类
@EnableSwagger2 //表示启用 Swagger2，也可以添加到主启动类
public class Swagger2Config {

    // Swagger文本对象
    @Bean
    public Docket adminApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 分组的组名
                .groupName("adminApi")
                // api文档信息
                .apiInfo(adminApiInfo())
                // 创建一个过滤器的选择器对象
                .select()
                // 具体路径，使用正则表达式匹配
                // 只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }

    // adminApi的详细信息
    private ApiInfo adminApiInfo() {
       return new ApiInfoBuilder().title("尚融宝后台管理系统API文档")
                // 描述信息
                .description("本文档描述了尚融宝后台管理系统的各个模块的接口的调用方式")
                // 版本号
                .version("1.0.0")
                // 联系信息：三个参数分别是作者，网址，邮箱
                .contact(new Contact("ShiGuang", "https://srb.com", "admin@srb.com"))
                // 生成
                .build();
    }

    // Swagger文本对象
    @Bean
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }

    // webApi的详细信息
    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder().title("尚融宝网站API文档")
                // 描述信息
                .description("本文档描述了尚融宝网站的各个模块的接口的调用方式")
                // 版本号
                .version("1.0.0")
                // 联系信息：三个参数分别是作者，网址，邮箱
                .contact(new Contact("ShiGuang", "https://srb.com", "admin@srb.com"))
                .build();
    }
}

3、访问地址

swagger-bootstrap-ui 默认访问地址是：http://${host}:${port}/swagger-ui.html

比如：http://localhost:8110/swagger-ui.html

因为导入了国人开发的 ui 包，也可以使用的访问地址：http://${host}:${port}/doc.html

比如：http://localhost:8110/doc.html

4、Controller 上的注解

定义在类上

1
@Api(tags = "积分等级管理")

定义在方法上

1
2
@ApiOperation("积分等级列表")
@ApiOperation(value = "根据id删除数据记录", notes = "逻辑删除数据记录")

定义在参数上

1
@ApiParam(value = "数据id", example = "1", required = true)

例子

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Api(tags = "积分等级管理")
@CrossOrigin // 跨域问题解决
@RestController
@RequestMapping("/admin/core/integralGrade")
public class AdminIntegralGradeController {

    @Resource
    private IntegralGradeService integralGradeService;

    @ApiOperation("积分等级列表")
    @GetMapping("/list")
    public List<IntegralGrade> listAll() {
        return integralGradeService.list();
    }

    @ApiOperation(value = "根据id删除数据记录", notes = "逻辑删除数据记录")
    @DeleteMapping("/remove/{id}")
    public boolean removeById(
            @ApiParam(value = "数据id", example = "1", required = true)
            @PathVariable Long id) {
        return integralGradeService.removeById(id);
    }
}

5、实体类上的注解

entity 的实体类中可以添加一些自定义设置，例如：

1
2
3
4
5
@ApiModelProperty(value = "创建时间", example="2021-01-01 08:00:00")
private LocalDateTime createTime;

@ApiModelProperty(value = "更新时间", example="2021-01-01 08:00:00")
private LocalDateTime updateTime;