API 接口文档
给同事写模块技术文档、怕接口与参数讲不清时,AI 能说清模块解决的问题、整体架构与关键流程,整理对外接口与参数,并给每个关键接口一段可运行的调用示例。没给的历史报错它不编造、标【待补】,读者角色仍要你确认。
你需要准备
- 语言与框架版本,以及代码托管平台与仓库结构(GitHub / GitLab / 内部仓库)
- 模块代码或仓库路径,以及读者角色与需要一句话解释的关键术语
- 对外接口与参数(名称、类型、含义),以及接口的请求 / 返回样例或可运行代码片段(缺失先标【待补】)
- 依赖与运行 / 部署环境(版本、配置项、环境变量)
- 历史报错记录、issue 列表或运行日志(没有就标【待补】,不得编造常见报错)
怎么做
- 先声明语言与框架版本、托管平台与仓库结构、读者角色
- 若接口示例或配置含密钥、token,先脱敏
- 让 AI 先把对外接口与参数整理成清单草稿,确认无误后再按接口逐条展开文档并补可运行调用示例(提示词可直接复制)
- 核对【待补】项,补上环境变量、报错素材等后再发布文档
一句话提示词
我完成了一个【功能/模块】,代码在下面,语言与框架版本、代码托管平台(GitHub / GitLab / 内部仓库)与仓库结构、以及我能找到的历史报错 / issue / 运行日志我都先声明并附上,帮我写一份给同事看的技术文档:这个模块解决什么问题、整体架构和关键流程、对外提供的接口和参数、依赖和注意事项、常见报错怎么排查,并对关键术语做一句话解释;每个关键接口要给一段可运行的调用示例(请求样例 + 返回示例,密钥 / 域名用占位符替换后可跑);我未提供的接口细节、配置或报错素材请标【待补】,没有报错素材时不要编造常见报错,不要编造。
它会交付什么
- 技术文档:模块解决的问题、整体架构与关键流程(含关键术语的一句话解释)
- 对外接口与参数说明 + 每个关键接口一段可运行的调用示例(请求样例 + 返回示例,密钥 / 域名用占位符替换后可跑)
- 依赖与注意事项、常见报错与排查方法(依据你给的历史报错 / issue / 日志归纳,属 AI 归纳,需人工判断);缺素材处标【待补】
效果示例
输入一个订单模块的代码与接口清单 → 输出一份技术文档与接口调用示例;未给的环境变量说明标【待补】。(示例为示意;归纳为 AI 归纳,需人工判断)
常见问题
接口文档 / README 怎么写,能让没参与开发的人看懂?
把代码、接口清单、依赖与历史报错一起给 AI,并要求对关键术语做一句话解释;背景与流程会写成大白话。
接口没定还要写吗?
可以,未定的接口参数会标【待补】,定稿后回来补;每个关键接口会附一段可运行调用示例。
含密钥的配置能写进去吗?
不能。示例里的 token、密钥要先脱敏,文档里用占位符。
没有报错记录,常见报错那一节怎么办?
没素材时不编造,该节标【待补】,等你补上 issue 或日志再让它归纳。
一次能写多大模块?
建议一个模块一篇,多个模块先列总览再分篇,避免混在一起。