Java 开发如何用 AI 生成接口文档初稿?我现在会这样做

你好，这里是朝夕有光。上一篇我写的是，当我们接手老项目、看不懂代码时，可以先让 AI 帮我们把逻辑理清楚。这篇我想继续往前走一步：当你已经大概看懂这段代码了，下一步怎么把它整理成一版接口文档初稿。这个场景其实很常见。尤其是在日常开发里，接口一旦改动，常常就会出现这些问题：- 代码改完了，但文档还没补- 接口参数变了，别人照着旧文档调用- 返回字段新增了，前端还在用老结构- 自己知道怎么用，但新同事看文档还是一头雾水以前写接口文档，我最烦的就是一边看代码，一边回忆业务，再一边整理成能给别人看的文字。这件事不是难，但很碎。如果接口少还好，接口一多，文档就很容易落后。现在我会借助 AI 先出一版初稿，自己再补业务细节和边界条件。这样做不代表不用写文档，而是把最耗时间的“起草”这一步先交给 AI。

01

为什么接口文档总是难写很多人以为接口文档难写，是因为不会写字。

其实不是。真正难的是，你得同时处理三件事：1. 看懂代码2. 理清业务3. 用别人能看懂的话写出来这三个步骤里，最耗时间的通常是前两个。比如一个接口，代码里可能只是一段Controller 加Service 调用，看起来不长。但文档里你要写的东西却很多：- 接口是干什么的- 哪些参数必填- 哪些参数可选- 返回值每个字段代表什么- 哪些情况下会失败- 有没有特殊业务规则- 调用时要注意什么如果项目里的注释又少，很多时候只能自己一点点翻代码。一个接口看下来，不是不能写，就是很容易卡在“我大概知道，但不知道怎么组织成文档”的状态。这就是 AI 能帮上忙的地方。

02

先别急着让 AI 直接生成整篇文档很多人一上来就会说：text请根据这段代码生成接口文档。

这样也能出结果，但通常不够稳。

因为 AI 看到的只是代码，不一定知道你要的文档格式，也不一定知道你想强调哪些内容。

所以更好的方式，是先告诉它文档用途，再告诉它输出结构。

比如你是要给前端看，还是给测试看，还是给新同事看，写法都不太一样。

如果是给前端看，就要更强调参数和返回结构。

如果是给测试看，就要更强调场景、状态、异常分支。

如果是给新同事看，就要更强调业务背景和调用顺序。

也就是说，不是让 AI 随便总结，而是让它按你想要的方式整理。

03

我现在常用的提示词

下面这版，是我自己比较常用的一版接口文档生成提示词。

你可以直接复制，然后把接口相关代码贴进去。

请你扮演一名资深 Java 后端工程师和接口文档整理助手。

我会给你一段 Java 接口相关代码，请你根据代码整理一份接口文档初稿。

要求：

1. 先写一句话说明这个接口的作用

2. 再写接口的使用场景

3. 按照“请求方式、请求地址、请求参数、返回参数、异常情况、注意事项”几个部分组织内容

4. 如果代码里能看出字段含义，请帮我补充字段说明

5. 如果有可能存在歧义的地方，请明确标出来，不要瞎猜

6. 语言尽量简洁，适合放到正式接口文档里

7. 如果发现代码里缺少关键信息，请先列出需要我补充的问题

代码如下：

【粘贴 Controller、DTO、VO、Service 相关代码】

这版提示词有几个点比较重要。

第一，它不是让 AI “自由发挥”，而是给了明确的输出结构。

第二，它要求 AI 标出歧义。

这一点很关键。接口文档最怕的不是不完整，而是写错了还很像那么回事。

第三，它要求先列出缺失信息。

因为很多时候，代码里并不能完全看出业务规则，比如某些字段到底是必填还是系统自动生成，某个状态值到底能不能为 0，这些都需要人工补。

04

我一般会给 AI 哪些内容

如果你想让 AI 生成得更像样一点，不要只贴一个方法。

我通常会把下面这些内容一起给它：

Controller 方法

请求 DTO

返回 VO

05

AI 生成完之后，我会重点看这几处

AI 写出来的初稿，能帮你省第一轮时间，但不能直接原样发布。

我自己一般会重点检查这几类内容：

1. 参数说明对不对

特别是字段名和业务含义。

有些字段名看起来像一个意思，实际上项目里另有含义。

比如 type、status、flag、code 这种字段，最容易被 AI 解释得过于笼统。

2. 返回结果有没有漏

接口文档里最容易漏的是特殊返回。

比如：

参数非法时的返回

没权限时的返回

数据不存在时的返回

业务校验失败时的返回

这些如果不写清楚，调用方很容易踩坑。

3. 业务边界有没有写出来

接口文档不只是写“怎么传”，还要写“什么时候不能这么传”。

比如某个参数在某种状态下不能修改，或者某个接口只能在某个流程阶段调用，这些都要补上。

4. AI 有没有把话说太满

这一点我很在意。

AI 很喜欢把不确定的地方写得很确定。

比如它可能会直接说某个字段“用于保存用户昵称”，但实际可能是内部展示名，也可能是历史兼容字段。

所以凡是项目里不够明确的地方，我都会重新核对，不会直接照抄。

06

一个更实用的用法：先要初稿，再人工补全

我现在不太追求让 AI 一次写出完美文档。

更现实的做法是：

先让 AI 出初稿

自己补上业务背景

再补边界条件

最后统一成正式文档

这样效率会高很多。

因为 AI 最擅长的是帮你把零散信息先整理成一个框架。

它能帮你把参数、返回值、流程、注意事项先摆出来。

剩下的业务背景、命名习惯、历史原因，还是得你自己确认。

我觉得这种分工挺合理。

AI 做起草，我做人。

AI 负责快，我负责准。

07

我平时会怎么追问

如果 AI 生成了一版文档，我通常不会马上结束，而是继续追问几轮。

比如：

请把这份接口文档整理成适合贴到项目 Wiki 的格式。

或者：

请补充这个接口可能出现的异常场景和调用限制。

或者：

请根据这段代码，列出前端调用时最容易踩坑的几个点。

这些追问会让文档更接近实际使用场景。

尤其是最后一个问题，我觉得很好用。

因为文档不是给自己看的，是给别人用的。

如果能提前把调用方容易踩坑的地方列出来，文档的价值会高很多。

08

最后

对我来说，AI 写接口文档最有价值的地方，不是“它直接帮我写完了”。

而是它让我把原本分散在代码里、脑子里、沟通里的信息，先快速拼成一版结构。

以前写文档，我可能要先看半天代码，再想怎么组织语言。

现在我会先让 AI 帮我出一个框架，再自己补细节。

这样一来，文档更容易开始写，也更容易写完。

这篇其实还是延续前两篇的思路：

不是把 AI 讲得很神，而是记录一个普通 Java 开发，在真实工作里怎么用 AI 少做一点重复劳动，多留一点精力给真正要判断的地方。

下一篇我准备写一个更贴近日常协作的场景：

程序员周报不会写的时候，怎么用 AI 把流水账整理成能看的成果表达。

如果你现在手头正好有一个接口要补文档，可以先试试这版提示词。

先让 AI 给你一版初稿，再自己把它修成能用的文档。