Three Common Failure Scenarios First
Many indie developers and small teams have already tried using AI to write API documentation and error code references, but the results are often disappointing. The most common failure patterns include:
Failure #1: Treating AI as a typist, generating all documentation in one conversation.
Some people simply toss a prompt like "write the documentation for this API" at the AI, then paste in the entire codebase or OpenAPI file. The result is a document that looks neat but is hollow—every endpoint has "request parameters" and "response examples," but the error code section is entirely fabricated, with made-up entries like "10001 Parameter Error" that don't exist in the codebase at all. After the documentation is sent to users, they try to troubleshoot based on it and only get more confused.
Failure #2: Making AI "guess" without real context for error codes.
Error code documentation is where things go wrong most easily. It requires real business semantics: under what conditions each code is triggered, what structure the backend returns, and how the frontend should prompt the user. If you only give the AI a list of error codes, it will generate a bunch of "universal but useless" descriptions—"System busy, please try again later" could be applied to half the codes. This kind of documentation might as well not exist; users still have no idea what they did wrong after reading it.
Failure #3: Freezing the documentation once written, never updating it when code changes.
AI writes documentation so fast that teams mistake it for a one-time task. Three months later, the API has three new error codes and two changed fields, but the documentation is still the initial version. Users integrate based on stale docs and step on the same landmines all over again. AI accelerated the output, which made people overlook the fact that documentation is a living artifact that needs maintenance.
These three failures share a common root cause: it's not that AI is incapable—it's that the way it's being used compresses its capabilities into a "text formatting tool." The right approach is to treat AI as a collaborator that needs to be fed sufficient context, needs to be verified, and can be integrated into a process.
What AI Can Actually Do for Users
Now that we've clarified the wrong ways to use AI, let's define what it can genuinely handle in this task:
- Extracting interface structure from code: Given real route definitions, Controller code, or OpenAPI/Swagger files, AI can accurately extract paths, methods, parameters, and authentication methods without fabricating anything.
- Generating structured error code reference tables: As long as you provide real error code definitions (enum classes, constant files, exception handling code), AI can generate a four-column table of "error code — trigger condition — response example — troubleshooting suggestions," which is exactly the part people are most likely to skimp on when writing by hand.
- Filling in user-perspective troubleshooting guides: AI excels at writing "here's what step you might have gotten wrong" for each error code from the perspective of "a developer integrating for the first time"—for example, whether a 401 means an expired token or a malformed one, and how to handle each case.
- Generating ready-to-run request examples: Including calling examples in multiple languages like curl, Python, and JavaScript, along with corresponding success/failure response payloads.
- Ongoing maintenance: After code changes, feed the diff to AI for incremental updates instead of regenerating the entire documentation from scratch.
The Right Workflow
Step 1: Prepare real materials. This includes the OpenAPI file (or route code for the main endpoints), the source code defining error codes (enums or constant files), the response structure from your unified exception handling, and two or three real request/response payloads. This step determines the lower bound of documentation quality.
Step 2: Feed materials to AI in batches, starting with the error code table. Error codes are the most hallucination-prone part and must be generated based on source code. Have the AI output a Markdown table, with trigger conditions annotated for every code.
Step 3: Manually verify, focusing on where "AI improvises." Check each error code against the source code to confirm it actually exists and that the trigger condition descriptions are accurate. Delete any fabrications immediately, and explicitly state in your prompt "only use the error codes I provide."
Step 4: Generate the interface documentation and example code. Use the verified error code table as context, then generate the interface documentation so that the error codes in response examples reference real data.
Step 5: Build a habit of incremental updates. Every time the code changes, give the relevant diff and documentation sections to AI for synchronized updates, and mark the update date in the documentation.
A Reusable Prompt Template
你是一位API文档工程师。请根据我提供的【真实源码材料】生成错误码说明文档。
规则:
1. 只使用我提供的错误码,禁止编造任何不存在的错误码或字段。
2. 如果信息不足,在对应条目标注【待补充】,不要自行脑补。
3. 输出为Markdown表格,包含五列:
错误码 | 错误名称 | 触发条件 | 返回示例(JSON) | 建议排查步骤
4. 返回示例必须符合我给出的统一响应结构。
5. 排查步骤站在首次接入的开发者视角,写具体的检查动作,
例如"检查Authorization头是否携带Bearer前缀",不要写"检查参数"这类空话。
材料如下:
【错误码定义源码】:
{粘贴枚举/常量定义}
【统一异常处理的返回结构】:
{粘贴响应结构代码}
【真实报文示例】:
{粘贴1-2个真实请求响应}
【业务背景一句话说明】:
{例如:面向第三方开发者的支付回调接口}The key to this template lies in rules 1 and 2—they directly target the two most common failure points mentioned above: "fabricated error codes" and "generic filler text."
Before-and-After Comparison
Take a small-to-medium project with 20 endpoints and 35 error codes as an example (this is a hypothetical scenario, not real data):
| Dimension | Manual Writing | With Proper AI Usage |
|---|---|---|
| Time for initial documentation | 2-3 days, often delayed | First draft plus verification done within half a day |
| Error code documentation completeness | Usually only code and name, omitting troubleshooting advice | Every code includes trigger conditions and troubleshooting steps |
| Multi-language call examples | Usually one language or none at all | Full coverage of curl/Python/JS |
| Syncing docs after code updates | Depends on self-discipline, often months behind | Feed diff to AI, incremental changes done in minutes |
| User integration support tickets | Repeatedly answering the same questions | Significantly reduced; the documentation itself is self-service |
More importantly, the quality floor shifts: when writing documentation manually, the most commonly omitted part is precisely the troubleshooting guidance that's most valuable to users; AI, facing no cost pressure, will fill that gap. Human effort can then focus on where AI is most error-prone—verifying accuracy.
A Few Additional Tips
- Model selection: Documentation generation doesn't demand much from a model, but for error code verification, it's advisable to use a more capable model to reduce misreadings of source code. Pricing varies significantly across models—check the official pricing page and choose according to your needs.
- Run a "cold read test" after generating the documentation: Have the AI play the role of a developer who has never seen the API before, then try to answer three typical questions using only the documentation. This will expose blind spots.
- Store the prompt template in your team's knowledge base: This turns documentation maintenance from "one person's task" into "a process anyone can complete in ten minutes."
API documentation and error code references are, by nature, part of the product. They were neglected in the past because writing them was tedious and time-consuming; now AI has driven the cost down to near zero, and all that remains is building the habit. If your project happens to need LLM capabilities to assist with this kind of documentation workflow, check out https://api.thistoken.ai/register —put AI to work in a real process, not as a typist.
---
Tired of juggling provider integrations? Register at https://api.thistoken.ai/register and call every model through one base_url.
Vous voulez essayer Token.AI ?
Créez une API Key au niveau du projet, activez les canaux dans la console et configurez le routage, les budgets et les journaux d'audit.
注册 ThisToken.AI 并获取 API Key