每日Skill学习 — API接口文档助手(api-doc-writer)#

📋 标准文档模板#

这个 skill 提供了一个非常完整的文档模板，包含以下核心部分：

1. 接口概览表 — 按模块分类展示接口数量和负责人，一眼就能了解项目整体规模

2. 通用说明区 — 集中定义认证方式、请求格式、响应格式、业务状态码，避免每个接口重复说明

3. 接口详情 — 每个接口包含：

• 接口地址（HTTP 方法 + URL）
• 请求参数表（参数名、类型、位置、必填、说明）
• 请求示例
• 成功响应示例
• 错误响应示例

4. 接口变更记录 — 版本 + 日期 + 变更内容 + 变更人，追根溯源

🎯 使用场景#

• 新项目启动时 — 快速搭建文档骨架，团队统一风格
• 前后端对接 — 后端写文档，前端照着开发，减少沟通成本
• API 评审 — 有了标准模板，评审时只看设计是否合理，不用再纠结格式
• AI 辅助生成 — 告诉 AI 接口逻辑，按照模板格式自动生成文档

1. 统一响应格式设计#

模板采用了国内常见的 code + message + data 三段式响应结构：

1
{
2
  "code": 0,
3
  "message": "success",
4
  "data": {}
5
}

这个设计的优点在于业务状态码和 HTTP 状态码分离——HTTP 状态码只表示传输层结果（200=请求到达），业务状态码表示业务层结果（0=成功，1001=参数错误……）。这样前端不需要同时处理两种状态码的逻辑，统一在 HTTP 200 下处理业务码即可。

2. 状态码体系化#

skill 定义了一套业务状态码规范，按千位分段：

这种分段方式让错误码自带分类信息，看到 2001 就知道是认证问题，看到 5001 就知道是服务端炸了，排查起来效率高很多。

3. RESTful 规范总结#

skill 简明扼要地总结了 RESTful 的核心原则：

• HTTP 方法语义：GET 查询、POST 创建、PUT 完整更新、PATCH 部分更新、DELETE 删除
• URL 命名：名词复数、小写、连字符分隔、不用动词（/getUser ❌ → /users ✅）

这些看起来是基础，但实际开发中违反的情况比比皆是。有个 checklist 在手，设计接口时对照一下能少走很多弯路。

4. 安全建议不敷衍#

最后的安全建议虽然简短，但每一条都是实打实的重点：

• 敏感信息加密传输（HTTPS 是底线）
• Token 过期机制（别搞永久 Token）
• 接口调用频率限制（防刷）
• 参数校验过滤（永远不要相信客户端输入）

第一步：复制模板#

把 skill 中的模板复制到你项目的文档目录（推荐 docs/api.md），填写基本信息：

1
版本：V1.0
2
更新日期：2026-04-21
3
维护人：你的名字

第二步：定义通用规则#

根据项目实际情况修改通用说明部分：

• 确认认证方式（Bearer Token / API Key / OAuth2）
• 定义业务状态码体系
• 确定分页格式（游标分页 / offset-limit）

第三步：逐个接口填充#

按照模板格式，为每个接口编写文档。推荐先写文档再写代码——文档即设计，设计通过评审再动手，能避免大量返工。

第四步：配合 AI 使用#

在 OpenClaw 中安装后，可以直接让 AI 助手帮你生成文档。比如描述一个接口需求：

帮我写一个用户注册接口文档，POST /api/v1/auth/register，需要 username、email、password 三个参数，返回用户ID和token

AI 会按照模板格式输出完整文档。