Knife4j 生成 API 文档的方法（评测平台接口管理实践）

接口文档和代码脱节，是前后端协作里绕不开的隐形损耗。平台前后端分离，前端、第三方集成方都依赖接口文档，可文档一旦跟不上迭代，前端就只能”猜字段”，猜不对就来群里问后端，一天能被同一个问题打断好几回。我先后对比过纯 Swagger UI、Apifox 自动同步、自建文档站几种方案，最终选了 Knife4j（Swagger 的国产增强版），因为它能让代码即文档、文档能调试、调试能带鉴权，把团队协作的沟通成本实实在在降了下来。下面把选型过程、集成步骤和踩过的坑完整写一遍。

一、为什么不用纯 Swagger UI

最开始我们直接上的是原生 Swagger UI，跑起来确实零成本，但用了一个月就撑不住了。接口一多就是平铺式列表，没有搜索没有折叠，找一个接口要点开好几层。调试时更难受，每次都要手动把 Authorization 头粘进请求里，测一个带鉴权的接口要反复复制粘贴。还有一个很现实的问题：界面全英文，团队内部和第三方对接方看文档的阅读成本都很高。

原生 Swagger UI 三大痛点：

1. 界面老旧：列表展示，无搜索、无折叠，几十个接口找半天；
2. 调试功能弱：不能全局带 token，每次粘贴 Authorization 头；
3. 不支持中文：团队对外分享时阅读成本高。

Knife4j 是基于 OpenAPI3 规范的国产增强版，上面三个痛点正好都补上了，所以作为第一候选进入我们的视野。

二、Knife4j vs 原生 Swagger UI

为了说服团队其他人一起迁移，我拉了一张对比表，把两个方案在关键维度上的差异直接摆出来：

平台选 Knife4j 的核心原因：全局 token 调试 + 中文界面 这两个特性直接省前端 50% 的沟通时间。实际跑了一个月之后，前端从”天天问字段”变成”自己查文档”，群里 @ 后端的消息肉眼可见地少了。这张对比表后来也成了我们对外技术分享时的常备素材。

三、平台集成步骤

确定选型之后，集成其实比想象中简单，核心就四步：加依赖、写配置类、给 Controller 补注解、启动访问。每一步都有需要注意的细节，我按顺序讲。

1. 加依赖

先在 pom.xml 里引入 starter。这里是第一个容易踩坑的地方：Spring Boot 3 的项目必须用 jakarta 命名空间的版本，老的依赖还在用 javax，直接编不过去。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

版本不建议追新，4.4.0 在社区里验证得多，相关报错和解决方案都比较齐全，出问题时好查。

2. 配置类

配置类做两件事：定义文档的基本信息和按模块分组。分组这一步建议一步到位，接口少的时候看不出来，等接口上了两百个，分组能救回大量翻文档的时间。

@Configuration
public class Knife4jConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("AI 大模型评测平台 API")
                .version("1.0.0")
                .description("前后端协作的 API 文档")
                .contact(new Contact().name("平台组").email("dev@eval.com")))
            .externalDocs(new ExternalDocumentation()
                .description("接口变更日志")
                .url("https://eval.example.com/changelog"));
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
            .group("管理后台")
            .pathsToMatch("/api/admin/**")
            .build();
    }
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("用户端")
            .pathsToMatch("/api/**")
            .pathsToExclude("/api/admin/**")
            .build();
    }
}

这里有个细节：pathsToMatch 和 pathsToExclude 要配合使用，把管理后台和用户端的接口拆成两个分组，前端、第三方各看各的，谁也不受对方接口干扰。

3. Controller 加注解

配置就绪后，剩下的工作就是给每个 Controller 补注解。平台的做法是：Controller 类上加 @Tag 说明模块职责，接口方法上加 @Operation 写清楚摘要和参数说明。

@Tag(name = "评测任务", description = "评测会话的创建、查询、删除")
@RestController
@RequestMapping("/api/eval/session")
public class EvalSessionController {
    
    @Operation(summary = "创建评测", description = "提交 question 跑多模型")
    @PostMapping
    public BaseResponse<Long> create(@RequestBody @Valid EvalCreateRequest req) {
        return ResultUtils.success(evalService.create(req));
    }

    @Operation(summary = "查询评测详情")
    @Parameter(name = "id", description = "评测 ID", in = ParameterIn.PATH)
    @GetMapping("/{id}")
    public BaseResponse<EvalSessionVO> get(@PathVariable long id) {
        return ResultUtils.success(evalService.getVO(id));
    }
}

注意 @Tag 的 description 一定要写完整，Knife4j 的分组、搜索都依赖这一段描述，写得越全，别人搜到的概率越高。

4. 启动访问

启动项目后访问 http://localhost:8080/doc.html 就能看到完整文档。如果看到的是空白页，先检查依赖版本和分组配置，这两个地方出问题的概率比较高。

四、平台上的典型用法

集成完成后，Knife4j 慢慢变成团队日常工具，下面几个用法是实际使用中频率比较高的，每个都解决过一个真实痛点。

全局 Token

平台接口大部分要登录态，没有全局参数的时候，每次调试都要粘 token。在「文档管理 → 全局参数」里加一个 Authorization 头：

参数名: Authorization
参数值: Bearer eyJhbGciOiJIUzI1NiJ9...

所有接口调试自动带这个头，不用每次粘贴。这一步做完，前端调试效率的提升是很直接的。

接口搜索

接口多了之后（平台 200+ 接口），搜索 prompt 直接定位到提示词相关 6 个接口，省去翻目录。树形导航加全文搜索配合使用，找接口的速度比之前快了一个量级。

离线文档导出

给第三方对接方发文档时，导出 Markdown 或 Word，对方离线看完整列表，不用登录平台。第三方反馈说这个功能比截图传接口信息正规多了，对接周期也缩短了不少。

在线调试

前端开发时直接在 Knife4j 上调接口看返回，比 Postman 方便（因为 Knife4j 上看到的 schema 就是后端真实定义）。参数结构有疑问的时候，直接在文档里展开看字段说明，不用再翻后端代码。

五、生产环境安全

文档在开发环境随便开没有问题，但上线前必须把安全配置做好。第一次部署生产环境时，我们发现 /doc.html 竟然可以匿名访问，整个接口结构都暴露在外面，赶紧补上了 Basic 鉴权。

application-prod.yml：

knife4j:
  enable: true
  production: true        # 生产环境严格模式
  basic:
    enable: true          # 开启 Basic 鉴权
    username: docadmin
    password: ${DOC_PASSWORD}  # 从环境变量读

密码用环境变量注入，不要写死在配置里。开启 production 严格模式后，文档默认折叠、调试参数打码，进一步降低被外部爬取的风险。

六、与 Postman/Apifox 的取舍

很多团队会纠结”有 Postman/Apifox 为什么还要 Knife4j”，我们的结论是它们定位不同，不冲突。把三者摆在一起看更清楚：

平台不强迫团队只用 Knife4j：Knife4j 用于”代码内调试”和”日常查字段”，复杂场景（环境变量、Pre-request Script）还是用 Apifox。两者互补而不是二选一。

七、踩过的坑

整个接入过程不是一路顺风，下面几个坑每个都花了不少排查时间，写出来免得后来人再踩一遍：

• 依赖冲突：Knife4j 4.x 已包含 springdoc-openapi 核心，千万不要再引 springdoc-openapi-starter-webmvc-ui 或 springfox，启动直接报 bean 冲突。
• Jakarta 命名空间：Spring Boot 3 必须用 knife4j-openapi3-jakarta-spring-boot-starter，老的 knife4j-openapi3-spring-boot-starter 还在用 javax。
• 对象属性不显示：实体类字段没加 @Schema 注解，Knife4j 只显示 Object。给字段加 @Schema(description="...") 即可。
• 继承类的字段缺失：父类字段在 Knife4j 上不显示。给子类字段也加注解，或用 @Schema(implementation = Parent.class)。
• WebFlux 不兼容：Knife4j 默认适配 Spring MVC，WebFlux 项目要用响应式版（knife4j-openapi3-jakarta-spring-boot-starter-reactive）。
• 生产环境暴露：默认 /doc.html 公开可访问，记得配生产鉴权或 knife4j.production=true 隐藏。

八、平台自定义扩展

基础功能够用之后，我们又基于 Knife4j 做了几处定制，让文档更贴合平台的实际情况：

1. 环境切换：下拉切换 dev/staging/prod，自动带不同 baseUrl。
2. MD5 签名调试：第三方接口对接需要签名，平台在 Knife4j 上预置了 sign 拦截器。
3. 统一 Header 注入：除 Authorization 外，平台所有接口需要 X-Request-Id，Knife4j 全局注入。
4. Mock 模式：knife4j.setting(mock=true) 调试时返回 Mock 数据，避免污染测试库。

这几项都不需要改动 Knife4j 源码，基于它暴露的配置和拦截器接口就能完成，维护成本很低。

九、配合 CI 流程

文档问题在于”改完代码忘了更新文档”。我们在 CI 里加了”接口变更检测”，把文档漂移挡在合并之前：

# GitHub Actions
- name: OpenAPI diff check
  run: |
    knife4j-cli export > openapi.json
    diff <(git show HEAD~1:openapi.json) openapi.json

接口 schema 变化（字段增删、类型变化）会在 PR 显眼提示，强制开发者更新文档。这条流水线上线后，文档和代码脱节的情况基本消失了。

到这里，Knife4j 从选型、集成到安全加固、CI 联动的完整链路就走通了。文档这件事没有银弹，但只要让”写文档”的成本趋近于零，团队自然愿意维护。

常见问题（FAQ）

Q1：为什么不用 Apifox 自动同步？

Apifox 同步需要 web hook + 解析 OpenAPI spec，链路多一环。Knife4j 直接读运行时元数据，”零延迟”同步。

Q2：Knife4j 性能怎么样？

接口数 < 500 时毫秒级加载，500+ 接口要做"分组"（@Tag 分类）才不会卡。平台 200 接口拆 4 组，体验流畅。

Q3：要不要把所有 Controller 都加注解？

必须。Knife4j 只扫描带注解的方法和类。不加注解的接口不会出现在文档里，前端就只能”猜”。