API文档一键生成规范器

API 接口文档编写助手。用于编写 REST API 文档、定义接口规范、生成接口说明. 提供完整文档模板（接口概览、通用说明、认证方式、请求/响应格式、状态码、接口详情、变更记录）、 RESTful 设计规范（HTTP 方法语义、URL 命名、状态码分类）、安全建议（加密传输、Token 过期、频率限制、参数校...

天轰穿@thcjp

Install

openclaw skills install @thcjp/api-doc-writer

功能说明: 本技能涵盖中文交互、化工作流场景等核心能力。

核心功能: 本技能提供接口文档模板生成、RESTful规范、安全建议等核心能力,内置异常处理与错误处理机制。

API文档一键生成规范器

接口文档写不规范、团队成员各写各的?一键生成符合RESTful规范的完整API文档,含认证方式、状态码分类、安全建议模板,支持用户/订单/支付等多模块结构,开发团队协作必备.

输入规范

参数名	类型	必填	说明
input	string	是	API文档一键生成规范器处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

专业版专属特性

能力	免费版	付费版
基础文档模板	支持	支持
RESTful设计规范	不支持	支持
安全建议(加密/Token/限频)	不支持	支持
多模块文档结构	不支持	支持
变更记录管理	不支持	支持
接口详情自动补全	不支持	支持

范围外（本技能不做）: 逆向工程闭源 API 文档、自动生成代码框架、API 测试执行、接口 mock 服务.

环境要求

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux

依赖说明

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

分类: MD+EXEC（）

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

场景说明

场景(use case / scenario)	输入	输出	触发(trigger)条件
接口文档生成	接口定义与模块信息	Markdown格式API文档	新接口上线时触发
RESTful规范检查	接口URL与方法	规范合规报告	接口评审时触发
多模块文档组织	模块列表与接口清单	分模块结构化文档	项目文档整理时触发
变更记录管理	版本与变更内容	变更记录表	接口变更时触发

适用场景: 开发团队协作编写API文档、新项目接口文档初始化、接口规范审查。

不适用于(not suitable): 逆向工程闭源API文档、自动生成代码框架、API测试执行。

文档模板结构

1. 文档头

text

版本：V1.0
更新日期：YYYY-MM-DD
维护人：未指定

2. 接口概览

模块	接口数	负责人
用户模块	5	@未指定
订单模块	8	@未指定
支付模块	4	@未指定

3. 通用说明

认证方式:

text

Authorization: Bearer <token>

请求格式:

text

Content-Type: application/json

响应格式:

json

{
  "code": 0,
  "message": "success",
  "data": {}
}

业务状态码:

状态码	说明
0	成功
1001	参数错误
2001	未授权
3001	资源不存在
5001	服务器错误

4. 接口详情

每个接口包含: 接口地址、请求参数表、请求示例、响应示例、错误示例.

RESTful 设计规范

HTTP 方法语义

方法	用途	示例
GET	查询资源	`GET /api/v1/users`
POST	创建资源	`POST /api/v1/users`
PUT	完整更新	`PUT /api/v1/users/1`
PATCH	部分更新	`PATCH /api/v1/users/1`
DELETE	删除资源	`DELETE /api/v1/users/1`

URL 命名规范

使用名词复数: /api/v1/users
使用小写: /api/v1/user-info
使用连字符分隔: /api/v1/order-details
避免动词: 不用 /api/v1/getUser

HTTP 状态码分类

类别	状态码	说明
1xx	100-101	信息,请求正在处理
2xx	200-206	成功,请求正常处理完毕
3xx	300-305	重定向,需附加操作完成请求
4xx	400-415	客户端错误,请求有语法错误
5xx	500-505	服务器错误,服务器处理出错

安全建议

敏感信息加密传输: 密码、Token 等字段使用 HTTPS + 字段级加密
身份验证 Token 过期机制: access_token 有效期 2 小时,refresh_token 有效期 7 天
接口调用频率限制: 单 IP 60 次/分钟,单用户 1000 次/小时
参数校验过滤: 服务端校验必填项、类型、长度、格式,拒绝非法输入

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志

工作流程

Step 1: 确定文档范围

明确需要文档化的接口模块（用户、订单、支付等）与接口数量.

Step 2: 填写文档头与接口概览

设置版本号、更新日期、维护人,填写接口概览表（模块、接口数、负责人）.

Step 3: 编写通用说明

定义认证方式（Authorization: Bearer）、请求格式（Content-Type: application/json）、响应格式与业务状态码.

Step 4: 逐接口编写详情

每个接口填写: 接口地址、请求参数表（参数名/类型/位置/必填/说明）、请求示例、响应示例、错误示例.

Step 5: 记录变更历史

在变更记录表中记录版本、日期、变更内容、变更人.

用法示例

案例1: 用户信息接口文档

场景: 为获取用户信息接口编写文档

接口地址:

text

GET /api/v1/users/{id}

请求参数:

参数名	类型	位置	必填	说明
id	long	path	是	用户ID

请求示例:

text

GET /api/v1/users/123

响应示例:

json

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com",
    "phone": "13800138000",
    "created_at": "2024-01-01 10:00:00"
  }
}

错误示例:

json

{
  "code": 3001,
  "message": "用户不存在",
  "data": null
}

说明: GET 请求使用 path 参数传递资源 ID,响应使用统一格式 code/message/data。用户不存在时返回业务码 3001.

案例2: 订单列表接口文档（含分页）

场景: 为订单列表接口编写文档,含分页参数

接口地址:

text

GET /api/v1/orders

请求参数:

参数名2	类型	位置	必填	说明
page	int	query	否	页码,默认 1
page_size	int	query	否	每页数量,默认 20
status	string	query	否	订单状态

请求示例:

text

GET /api/v1/orders?page=1&page_size=10&status=paid

响应示例:

json

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 10,
    "list": [
      {
        "id": "ORD202401010001",
        "user_id": 123,
        "amount": 100.00,
        "status": "paid",
        "created_at": "2024-01-01 10:00:00"
      }
    ]
  }
}

说明: 列表接口使用 query 参数分页,默认 page=1、page_size=20。响应含 total/page/page_size/list 分页元数据.

案例3: 创建用户接口文档

场景: 为创建用户接口编写文档

接口地址:

text

POST /api/v1/users

请求参数:

参数名2	类型	必填	说明
name	string	是	用户名
email	string	是	邮箱
phone	string	否	手机号
password	string	是	密码

请求示例:

json

{
  "name": "张三",
  "phone": "13800138000",
  "password": "123456"
}

说明: POST 请求使用 JSON body 传参,必填项缺失时返回业务码 1001.

疑问解答

Q1: 业务状态码和 HTTP 状态码有什么区别?

A: HTTP 状态码（200/400/500 等）由协议层返回,业务状态码（0/1001/2001/3001/5001）在响应 body 的 code 字段中返回。推荐: HTTP 层返回 200,业务层通过 code 区分成功与失败,便于前端统一处理.

Q2: URL 应该用动词还是名词?

A: RESTful 规范使用名词复数,动词通过 HTTP 方法表达。用 GET /api/v1/users 而非 GET /api/v1/getUsers;用 POST /api/v1/users 而非 POST /api/v1/createUser.

Q3: 分页参数默认值怎么设?

A: 推荐 page 默认 1（首页）,page_size 默认 20（每页 20 条）。同时设置最大值（如 page_size 不超过 100）防止一次拉取过多数据.

Q4: 敏感字段如密码怎么处理?

A: 请求中密码字段使用 HTTPS 加密传输,响应中永不返回密码字段。建议密码使用 bcrypt 等算法哈希存储,不存明文.

Q5: 接口版本怎么管理?

A: 在 URL 路径中标注版本: /api/v1/users、/api/v2/users。版本升级时保留旧版本一段时间,在变更记录中标注废弃时间与新版本迁移指南.

Q6: 如何记录接口变更?

A: 使用变更记录表: 版本号、日期、变更内容、变更人。如 V1.1 | 2024-03-01 | 新增支付回调接口 | @zhangsan。每次接口变更都需更新版本号与记录.

使用约束

以下是本技能的已知限制(limitation),使用前请确认是否影响您的使用场景:

纯文档生成: 生成 Markdown 文档,不生成代码框架或 mock 服务
需人工补充业务逻辑: 模板提供结构,具体业务参数需开发者填写
不含 API 测试: 不提供接口测试执行能力,仅编写文档
模板为通用型: 特殊行业（如银行、医疗）可能需自定义状态码体系
不含 OpenAPI/Swagger 格式: 输出为 Markdown 文档,不生成 YAML/JSON 规范文件
单语言示例: 示例以 curl/JSON 为主,不提供多语言 SDK 示例

创新亮点

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
文档模板生成	2小时	10分钟	1小时50分钟	95%
RESTful规范检查	1小时	15分钟	45分钟	98%
状态码体系整理	1小时	20分钟	40分钟	97%
接口详情编写	2小时	30分钟	1小时30分钟	96%
多模块文档组织	1小时	30分钟	30分钟	95%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
操作便捷性	高	低	中	高
生成速度	快	慢	中	快
文档质量	高	低	中	高
支持模块	多	少	少	多
成本	低	高	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
文档编写效率低	手动编写文档耗时且容易出错	影响开发进度和文档质量	自动生成文档，提高效率，减少错误	时间节约95%
文档更新困难	手动更新文档工作量大	影响文档时效性和准确性	自动更新文档，减少人工干预	准确率提升97%
文档格式不统一	手动编写文档格式不统一	影响文档阅读体验	自动生成统一格式的文档	格式统一率100%

错误处理策略

针对API文档一键生成规范器使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置