零碎02-接口文档管理

一、背景故事

二、解决方案分析

1. 静态文档方案

2. Swagger + Springfox

3. Knife4j增强方案

三、示例

1. 添加依赖

2. 配置Knife4j

3. 创建knife4j配置类

4. 启动Spring Boot项目并访问接口文档

5. 使用示例

6. 测试和使用

四、总结

一、背景故事

酷乐是一名技术栈不详、遇强则强的程序员。他在公司负责开发某个核心系统模块，常常面临接口文档管理的困扰。项目的开发人员和测试人员为了确保系统功能实现和测试验证，一直依赖接口文档来进行协作。然而，由于系统复杂度不断增加，接口文档不仅繁杂而且容易遗漏更新，测试人员和开发人员经常出现接口信息不一致的情况，这导致接口调试变得低效且费时。为了解决这个问题，酷乐决定改进公司接口文档的展示和管理方式，以便提高开发和测试的协同效率。

二、解决方案分析

在寻找高效的接口文档管理方式时，酷乐尝试了多种方案，每一次改进都带来了体验上的提升。

1. 静态文档方案

初期方案：团队使用Markdown或Excel等静态文档来记录接口信息。每次接口有变更时，文档需要手动更新，随着项目接口数量的增加，接口文档内容逐渐变得杂乱无章。
问题分析：静态文档的更新依赖人工，容易因疏漏导致文档与实际代码不符，且内容缺乏实时性，无法满足多人协作的需求。
小结：静态文档适用于早期的原型设计和接口定义，但在复杂项目中维护成本过高。

2. Swagger + Springfox

中期方案：酷乐团队决定使用Swagger生成接口文档，结合Springfox插件在Spring Boot项目中展示。Swagger根据代码注解自动生成文档，确保文档与接口保持一致。团队成员可以直接通过Swagger UI查看接口信息，无需手动编写。
使用方式：在接口代码中添加@Api、@ApiOperation等注解，Swagger可以生成接口的详细描述、参数和返回值示例。Swagger UI自动生成的页面简洁易用，接口变更会实时更新到文档。
优缺点：Swagger解决了文档一致性的问题，但Swagger UI界面较为简单，展示效果有限，难以满足复杂接口的使用需求。

3. Knife4j增强方案

现行方案：为进一步提升接口文档的易用性，酷乐引入了Knife4j。Knife4j是在Swagger基础上的增强工具，提供了更为友好的界面和功能，如接口分组、参数样例展示、全局参数配置等功能，提升了用户体验。
示例分析：在Spring Boot项目中集成Knife4j，只需引入knife4j-spring-boot-starter依赖，并在application.yml中进行简单配置，就可以直接生成具有分组和样例展示的接口文档。测试人员可以快速查找到需要的接口，开发人员也能方便地调试和验证接口。
实际效果：Knife4j的增强UI界面使得接口文档更具可读性，同时也支持团队自定义文档结构。基于Knife4j的文档生成不仅提升了开发效率，还使接口文档展示更专业、直观，受到团队一致好评。

三、示例

在Spring Boot项目中接入Knife4j可以方便地生成接口文档，供开发人员和测试人员查看和使用。Knife4j是在Swagger基础上进行扩展的工具，提供了更友好的UI和一些增强功能。以下是如何集成Knife4j的步骤：

1. 添加依赖

在pom.xml中添加Knife4j的依赖。

springboot升级到3后之前的knife4j配置就要变了一下了。

<dependencies><!-- springframework --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.1.4</version></dependency>
<!-- Knife4j依赖 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency>
</dependencies>

2. 配置Knife4j

在Spring Boot的配置文件application.yml中添加Knife4j的相关配置：

server:port: 8088

spring:application:name: demo-application

# knife4j的增强配置，不需要增强可以不配
knife4j:enable: true  # 是否启用Knife4j界面setting:language: zh_cn

3. 创建knife4j配置类

在src/main/java目录下新建一个配置类，用于配置knife4j的基本信息。

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/*** Knife4j configuration*/
@Configuration
public class Knife4jConfig {
@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI()// 接口文档标题.info(new Info().title("API文档").description("Spring Boot Knife4j API").version("1.0.0").contact(new Contact().name("Kule").url("https://lwer.site").email("958514155@qq.com"))); // 接口文档版本}
}

4. 启动Spring Boot项目并访问接口文档

启动Spring Boot项目后，可以在浏览器中访问以下URL来查看生成的接口文档：

访问Knife4j UI页面：http://localhost:8088/doc.html

讲个笑话：我多加了一个spring-boot-starter-security的依赖，访问就会跳转/login登录，以为是yaml配置里开启了knife4j的密码登录：
```
knife4j:enable: truesetting:language: zh_cnbasic:enable: true  #进入界面是否需要账号密码username: adminpassword: 123456
```

实际是：spring-boot-starter-security需要同时配合knife4j的账号密码。要么两者都不加，免密登录。

5. 使用示例

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

注解	说明
@Tag	用于说明或定义的标签
@Operation	用在类上,描述API操作的元数据信息，例如Controller，表示对类的说明
@Schema	用于描述实体类属性的描述、示例、验证规则等，比如POJO类及属性
@Parameter	加粗样式用于描述 API 操作中的参数,对HTTP请求参数进行描述

import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "Hello")
@RestController
@RequestMapping("/api/demo")
public class HelloController {@GetMapping("/hello")@Operation(summary = "Say hello")public String hello() {return "Hello World!";}
}