0. 前言

在前后端分离开发的过程中，前端和后端需要进行 api 对接进行交互，就需要一个 api 规范文档，方便前后端的交互，但 api 文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护 api 文档，加大了开发的工作量和困难，而 “丝袜哥” —— Swagger 的出现就是为了解决这一系列的问题。

1. Swagger

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

  • 使得前后端分离开发更加方便，有利于团队协作。
  • 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担。
  • 功能测试 。

Spring 已经将 Swagger 纳入自身的标准，建立了 Spring-swagger 项目，现在叫 Springfox。通过在项目中引入 Springfox ，即可非常简单快捷的使用 Swagger。

2. knife4j

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

目前，一般都使用 knife4j 框架。

注意事项

版本兼容性：Knife4j版本参考

PS：4.0版本以后

  • 区分 OpenAPI2 和 Swagger3 的 Maven 坐标 artifactId
  • OpenAPI2 规范服务端解析框架稳定在 springfox2.10.5
  • OpenAPI3 框架服务端解析跟随 springdoc 项目更新迭代

SpringBoot 3 只支持 OpenAPI3 规范。

3. 快速开始

PS：如下示例使用的 SpringBoot 版本为 2.7.3 ，规范是OpenAPI2(Swagger)

其他搭配可以查看官网：快速开始

3.1 引入依赖

自4.0版本开始，maven组件的 artifactId 已经发生了变化。引用组件maven坐标如下：

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

3.2 两种方式使用

第一种：配置文件式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
knife4j:
  enable: true
  openapi:
    title: Knife4j测试
    description: "`我是测试`,**你知道吗** # aaa" #支持 MarkDown 语法
    email: muyoukule@gmail.com
    concat: 木又枯了
    url: https://zz.muyoukule.cn
    version: v4.0
    license: Apache 2.0
    license-url: http://www.xx.com/
    terms-of-service-url: http://www.xx.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.muyoukule.controller

第二种：编程式

创建 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
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                // apiInfo()：配置 API 的一些基本信息，比如：文档标题title，文档描述description，文档版本号version
                .apiInfo(new ApiInfoBuilder()
                        .title("swagger-bootstrap-ui-demo RESTful APIs")
                        //支持 MarkDown 语法
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        //API服务条款
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact(new Contact("muyoukule", "https://zz.muyoukule.cn", "muyoukule@gmail.com"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.0版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.muyoukule.controller"))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

}

3.3 编写接口

IndexController.java 包含一个简单的RESTful接口，代码示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
@Api(tags = "首页模块")
@RestController
public class IndexController {
    
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name") String name) {
        return ResponseEntity.ok("Hi:" + name);
    }

}

启动SpringBoot工程，在浏览器中访问接口文档，地址：http://localhost:8080/doc.html 即可看到对应界面。

3.4 常用注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解 说明
@Api(tags = “01.xxx模块”) 用在类上，例如Controller，表示对类的说明
@ApiModel(description = “xxx的数据模型”) 用在类上，例如entity、DTO、VO
@ApiModelProperty(value = “xxx”, required = true, example = “示例值”) 作用在类方法和属性上，描述属性信息
PS：如果配置了 required=true，只是一种显示效果，Knife4j框架并不具备检查功能
@ApiOperation(value = “方法的用途”) 用在接口方法上，例如Controller的方法，说明方法的用途、作用
@ApiParam(“xxx参数说明”) 作用在参数、方法和字段上，类似@ApiModelProperty

我们也可以给请求的接口配置一些注释：

1
2
3
4
5
@ApiOperation("接口")
@PostMapping("/test")
public String test(@ApiParam("这个名字会被返回")String username){
   return username;
}

这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！！

更多细节推荐这篇文章：Knife4j系列