目录
一、背景故事
二、解决方案分析
1. 静态文档方案
2. Swagger + Springfox
3. Knife4j增强方案
三、示例
1. 添加依赖
2. 配置Knife4j
knife4j%E9%85%8D%E7%BD%AE%E7%B1%BB-toc" style="margin-left:160px;">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
knife4j%E9%85%8D%E7%BD%AE%E7%B1%BB">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!";}
}
6. 测试和使用
通过访问http://localhost:8088/doc.html即可看到基于Knife4j生成的界面。此界面可以方便地测试接口、查看接口详情等，非常适合日常的开发和测试需求。
四、总结
在解决接口文档展示的问题上，通过使用Knife4j展示接口文档，团队实现了接口定义与文档的一致性、实时更新和更优展示效果，有效解决了接口开发和测试中的协同问题。这一过程也体现了在快速发展的技术环境中，工具的迭代创新如何帮助技术团队更高效地协作与交付。
![2024-11-11 问AI: [AI面试题] 讨论人工智能的未来趋势和进步](/images/no-images.jpg)
