Api Doc Writer Free

API 接口文档编写助手免费版。用于编写基础 REST API 文档,提供文档模板、认证方式、请求/响应格式与基础 RESTful 规范。完整安全建议、多模块结构、变更记录、HTTP 状态码分类等高级功能需升级付费版。

Install

openclaw skills install @thcjp/api-doc-writer-free

API 接口文档编写器（免费版）

API 接口文档编写助手免费版。提供基础文档模板、认证方式、请求/响应格式与 RESTful 规范,快速生成结构化 API 文档。

升级提示: 完整安全建议、多模块结构、变更记录、HTTP 状态码分类、分页参数规范等高级功能为付费版专享。升级付费版解锁完整能力。

依赖说明

运行环境

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="your_api_key_here"

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

核心能力

基础文档模板: 接口概览、通用说明、认证方式、请求/响应格式
RESTful 规范: GET/POST/PUT/PATCH/DELETE 方法语义
业务状态码: 0/1001/2001/3001/5001 基础状态码体系
接口详情编写: 接口地址、请求参数表、请求示例、响应示例

付费版专享功能

以下功能在免费版中不可用,升级付费版解锁:

完整安全建议: 敏感信息加密、Token 过期机制、频率限制、参数校验
多模块结构: 用户模块、订单模块、支付模块等分模块文档组织
变更记录: 版本追踪、变更内容、变更人记录
HTTP 状态码分类: 1xx-5xx 完整分类说明
分页参数规范: page/page_size 默认值与最大值设置
URL 命名规范: 名词复数、小写、连字符等完整规范
错误示例编写: 每个接口的错误响应示例

处理: 按照skill规范执行付费版专享功能操作,遵循单一意图原则。输出: 返回付费版专享功能的执行结果,包含操作状态和输出数据。

基础文档模板

执行基础文档模板操作,处理用户输入并返回结果。

输入: 用户提供基础文档模板所需的参数和指令。

输出: 返回基础文档模板的处理结果。

执行基础文档模板操作，处理输入数据并返回结果
验证执行结果，确认输出符合预期格式
参考基础文档模板相关配置参数进行设置

RESTful 规范

执行RESTful 规范操作,处理用户输入并返回结果。

输入: 用户提供RESTful 规范所需的参数和指令。

输出: 返回RESTful 规范的处理结果。

执行RESTful 规范操作，处理输入数据并返回结果
验证执行结果，确认输出符合预期格式
参考RESTful 规范相关配置参数进行设置

技术细节

组件	说明	关键参数
`parser`	解析输入指令	`format`, `encoding`
`processor`	执行核心处理逻辑	`mode`, `timeout`
`output`	格式化输出结果	`format`, `encoding`

能力覆盖范围

本skill还覆盖以下能力场景: 编写基础、API、含模板、请求响应格式与基、接口文档编写助手、用于编写基础、提供文档模板、与基础、状态码分类等高级、功能需升级付费版。这些能力在上述核心功能中均有对应处理逻辑。

输出格式

执行结果以Markdown格式返回,包含操作状态(成功/失败)、处理摘要和具体输出数据。失败时返回错误码和错误信息,便于定位问题。

基础文档模板

文档头

text

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

通用说明

认证方式:

text

Authorization: Bearer <token>

请求格式:

text

Content-Type: application/json

响应格式:

json

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

业务状态码:

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

RESTful 基础规范

方法	用途	示例
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 命名规范（名词复数、小写、连字符、避免动词）与 HTTP 状态码 1xx-5xx 分类说明。

使用流程

Step 1: 确定文档范围

明确需要文档化的接口与参数。

Step 2: 填写文档头

设置版本号、更新日期、维护人。

Step 3: 编写通用说明

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

Step 4: 逐接口编写详情

每个接口填写: 接口地址、请求参数表、请求示例、响应示例。

提示: 如需编写错误示例、分页参数规范、安全建议等高级内容,请升级付费版。

命令参数说明

-MM-DD: 命令参数,用于指定操作选项
-Type: 命令参数,用于指定操作选项

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,参考错误处理章节获取恢复步骤。

命令参数说明

-Type: 命令参数,用于指定操作选项
-MM-DD: 命令参数,用于指定操作选项

命令参数说明

-MM-DD: 命令参数,用于指定操作选项
-Type: 命令参数,用于指定操作选项

命令参数说明

-Type: 命令参数,用于指定操作选项
-MM-DD: 命令参数,用于指定操作选项

命令参数说明

-MM-DD: 命令参数,用于指定操作选项
-Type: 命令参数,用于指定操作选项

命令参数说明

-Type: 命令参数,用于指定操作选项
-MM-DD: 命令参数,用于指定操作选项

命令参数说明

-MM-DD: 命令参数,用于指定操作选项
-Type: 命令参数,用于指定操作选项

命令参数说明

-MM-DD: 命令参数,用于指定操作选项
-Type: 命令参数,用于指定操作选项

命令参数说明

-Type: 命令参数,用于指定操作选项
-MM-DD: 命令参数,用于指定操作选项

案例展示

案例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"
  }
}

升级提示: 付费版提供错误示例编写（如用户不存在返回 3001）与完整安全建议。

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

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

接口地址:

text

POST /api/v1/users

请求参数:

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

请求示例:

json

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",
  "password": "123456"
}

升级提示: 付费版提供分页参数规范（page 默认 1,page_size 默认 20）与频率限制建议。

错误处理

错误场景	业务码	原因分析	处理方式
参数缺失	`1001`	必填参数未传	检查请求参数表,补全必填项
未授权	`2001`	`Authorization: Bearer` 头缺失	重新获取 token 后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
资源不存在	`3001`	请求的资源 ID 不存在	核实资源 ID 是否正确
服务器错误	`5001`	服务端处理异常	联系后端排查日志
功能不可用	—	需要高级功能（安全建议、变更记录等）	升级付费版解锁

常见问题

Q1: 免费版支持哪些文档功能?

A: 免费版支持基础文档模板、认证方式、请求/响应格式、业务状态码与 RESTful 方法语义。安全建议、多模块结构、变更记录等高级功能需升级付费版。

Q2: 免费版能编写分页参数文档吗?

A: 免费版不包含分页参数规范。升级付费版可获取 page 默认 1、page_size 默认 20 的分页参数规范与最大值设置建议。

Q3: 如何记录接口变更?

A: 免费版不包含变更记录功能。升级付费版可使用变更记录表（版本号、日期、变更内容、变更人）进行版本追踪。

Q4: 免费版包含安全建议吗?

A: 免费版不包含安全建议。升级付费版可获取敏感信息加密传输、Token 过期机制（access_token 2小时/refresh_token 7天）、频率限制（60次/分钟）、参数校验等完整安全建议。

Q5: URL 命名规范在免费版中有吗?

A: 免费版仅提供 HTTP 方法语义表。升级付费版可获取完整 URL 命名规范（名词复数、小写、连字符分隔、避免动词）。

已知限制

无安全建议: 不含加密传输、Token 过期、频率限制等安全规范
无多模块结构: 不支持用户/订单/支付等分模块文档组织
无变更记录: 不支持版本追踪与变更历史记录
无 HTTP 状态码分类: 不含 1xx-5xx 完整分类说明
无分页参数规范: 不含 page/page_size 默认值与最大值设置
无错误示例: 不提供每个接口的错误响应示例

升级付费版 解锁: 完整安全建议、多模块结构、变更记录、HTTP 状态码分类、分页参数规范、URL 命名规范、错误示例编写等完整能力。