A Truth Most Developers Silently Share

The API is done, but the docs aren't written yet. This isn't laziness—it's a structural problem:

• You get into flow when writing code, but only suffering when writing documentation
• Error codes are scattered throughout the codebase, and nobody can say for sure how many are defined in total
• After the first version of the docs was written, the code went through three rounds of changes while the docs are still stuck at v0.1
• When a user reports an error and asks "what does 40302 mean?", you have to dig through the code yourself

I spent two years maintaining APIs on a small team. The "catching up on docs" phase before every release took an average of 6-8 hours, and the quality of the output was severely disproportionate to the time spent—the error code table regularly missed newly added codes, and parameter descriptions were copy-pasted from the previous parameter with a couple of words changed.

Then I tried handing this task over to AI. Below is the complete process and a quantified comparison.

What AI Can Do for This

Let me give you the conclusion first: AI can take on four types of work in API documentation scenarios:

1. Extract interface definitions from code and comments. Paste code snippets from controllers and handlers to AI, and it can organize them into standardized interface documentation: request methods, paths, parameter names, types, required flags, and example values.

2. Consolidate and deduplicate error codes. Feed the scattered error code definitions (constant files, enums, exception classes) to AI, and have it output a table of "code—meaning—trigger condition—what the user should do," flagging any suspected duplicates or semantically conflicting codes.

3. Rewrite for different audiences. The same interface needs completely different levels of detail for frontend colleagues versus third-party integrators. AI can generate both versions from the same source material.

4. Detect "documentation debt." Have AI compare old docs against new code, listing outdated parameters, missing descriptions, and contradictory statements.

These four tasks share common traits: mechanical, repetitive, requiring cross-file information synthesis—exactly the kind of work humans do slowly and AI does fast.

My Actual Workflow

The whole process has four steps and takes one afternoon:

Step 1: Gather the raw materials (about 40 minutes). Export all interface code definitions, error code enums, and existing old docs. No need to format anything—AI has a high tolerance for messy input.

Step 2: Generate the first draft of interface docs (about 30 minutes). Paste code to AI in batches of no more than 10 interfaces each, to avoid omissions caused by long contexts.

Step 3: Generate the master error code table (about 20 minutes). Do this as a separate round, focusing on having AI perform deduplication and conflict detection—this is the step where manual work is most error-prone.

Step 4: Manual proofreading (about 1.5 hours). Check for default values AI fabricated and parameter meanings it was unsure about. This step cannot be skipped—AI will occasionally "plausibly guess" a default parameter you never wrote.

Before and After: An Efficiency Perspective

Using a medium-sized API project (about 40 interfaces, 130 error codes) as a reference:

Assuming two release iterations per month, documentation maintenance drops from about 8 hours to 1.5 hours per month. For a small team, that's recovering one full workday every month. And the API call costs of using AI tools are negligible compared to the labor hours saved—check the official pricing page for specifics.

More important is the hidden improvement in quality: for the first time, the error code table was "complete, deduplicated, with user-facing handling suggestions for every code," and inquiries from integrators visibly dropped.

A Reusable Prompt Template

This is the template I settled on after repeated tweaking—just replace the placeholders:

你是一位资深API文档工程师。请根据我提供的代码，生成规范的API文档。

【输入材料】
<粘贴接口代码 / 错误码定义 / 相关注释>

【输出要求】
1. 每个接口包含：接口名称、请求方法与路径、功能说明、
   请求参数表（参数名/类型/必填/说明/示例值）、
   响应字段说明、一个完整请求与响应示例
2. 错误码整理为表格：错误码 / 含义 / 触发条件 / 用户处理建议
3. 标记出以下问题（如有）：
   - 疑似重复或语义冲突的错误码
   - 代码中存在但注释缺失的参数
   - 你不确定而做了推测的地方，用【待确认】标注
4. 语言风格：面向第三方开发者，简洁、准确，不用营销化措辞
5. 不要编造代码中不存在的信息；推测必须显式标注

【目标读者】<内部同事 / 第三方接入方>

Rules 3 and 5 are the key: forcing AI to expose its uncertainty turns "plausible-looking fabrications" into "explicitly marked items pending confirmation," which makes manual proofreading much more efficient.

A Few Hard-Earned Lessons

• Feed in batches. If you stuff 50 interfaces in at once, the parameter tables in the later sections start getting sloppy. Batches of around 10 work best.
• Do error codes as a separate round. When generated together with interface docs, error code tables are more likely to have omissions.
• Keep the AI's raw output for diffing. At the next version update, just have AI compare the old and new outputs, and the changes become obvious at a glance.
• Don't skip manual proofreading. AI can get you 80% of the way there; the remaining 20% of accuracy judgment is your responsibility alone—but 20% of the time is far less than 100%.

Final Thoughts

What makes documentation special is this: everyone knows it should be done, everyone procrastinates on it, because the return on investment is terrible. AI completely flips that ratio—when the cost of maintaining docs drops from "half a day" to "half an hour," it goes from being a burden to being a habit.

If your project happens to be integrating LLM capabilities and needs a stable API gateway and model service, check out this platform—registration here: https://api.thistoken.ai/register

---

Ready to try it yourself? Sign up at https://api.thistoken.ai/register to get your API key and start building.