需按五步完成金米来三系统api文档编写：一、配置km3-doc-config.json并校验权限；二、在接口函数上添加@km3-api注释块并规范填写字段；三、执行km3-doc generate命令生成文档；四、人工补全认证、错误码、限流等附录内容；五、通过路由比对和curl测试验证准确性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您需要为金米来三系统编写技术文档，特别是生成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标识或存在语法错误，如未闭合的引号或换行符截断字段值。
