需按五步完成金米来三系统API文档编写：一、配置km3-doc-config.json并校验权限；二、在接口函数上添加@km3-api注释块并规范填写字段；三、执行km3-doc generate命令生成文档；四、人工补全认证、错误码、限流等附录内容；五、通过路由比对和curl测试验证准确性。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如果您需要为金米来三系统编写技术文档，特别是生成API说明教程，则需遵循其内置的文档生成规范与结构要求。以下是完成该任务的具体步骤：

一、确认金米来三文档生成环境配置

金米来三支持通过注释解析自动生成API文档，前提是开发环境已正确安装并启用文档生成插件。该插件依赖于项目中特定格式的注释块及配置文件声明。

1、检查项目根目录是否存在km3-doc-config.json文件。

2、确认km3-doc-config.json中"sourceDir"字段指向包含API接口定义的源码路径。

3、验证"outputFormat"值为"markdown"或"html"，以匹配目标文档类型。

4、运行命令行工具km3-doc generate前，确保当前用户具有读取源码与写入输出目录的权限。

二、在代码中添加标准API注释块

金米来三仅识别以/** @km3-api开头的多行注释，并依据其中的键值对提取接口元数据。未按此格式书写的注释将被忽略。

1、在每个HTTP处理函数上方插入独立的注释块，起始行为/** @km3-api。

2、在注释块内逐行填写name:、method:、path:、summary:等必填字段，字段名后紧跟英文冒号与空格。

3、使用requestBody:描述请求体结构，字段名用双引号包裹，嵌套层级用点号连接，例如"user.name"。

4、使用responses:定义返回状态码及对应schema，每个响应项独占一行，格式为200: {"code": 0, "data": {}}。

三、使用CLI工具执行文档生成

金米来三提供命令行接口直接触发文档构建流程，输出内容严格依据注释解析结果，不依赖外部模板引擎。

1、打开终端并切换至项目根目录。

2、执行km3-doc generate --output ./docs/api，指定输出路径为相对路径./docs/api。

3、等待控制台显示✅ Documentation generated successfully提示。

4、检查./docs/api目录下是否生成了index.html（HTML模式）或api.md（Markdown模式）文件。

四、手动补全非注释覆盖的文档要素

金米来三自动提取能力不涵盖全局认证机制、错误码字典、调用频率限制等上下文信息，需人工补充至生成文档末尾的“附录”章节。

1、在生成的api.md文件末尾新增## 附录二级标题（若为HTML则对应<h2>附录</h2>）。

2、添加### 认证方式小节，注明所有接口统一采用Authorization: Bearer <token></token>头传递凭证。

3、插入错误码表格，列出400、401、429、500四类状态码及其code字段取值与含义。

4、在表格下方注明所有接口默认限流为每分钟60次，超出后返回429状态码。

五、验证生成文档的准确性与完整性

自动生成结果需与实际运行时接口行为一致，重点核对路径拼接、参数位置、响应字段是否存在遗漏或错位。

1、启动金米来三本地服务，访问http://localhost:8080/debug/routes获取实时路由列表。

2、将返回的JSON中每个path字段与生成文档中path:值逐条比对，确认无路径前缀缺失或斜杠冗余。

3、选取一个POST接口，在文档中查找其requestBody:描述，使用curl命令发送含该结构的请求，观察响应是否匹配responses:中定义的200 schema。

4、若发现某接口在文档中缺失，立即检查其上方注释是否遗漏@km3-api标识或存在语法错误，如未闭合的引号或换行符截断字段值。