back
loading skill details...
API 接口文档编写助手免费版。用于编写基础 REST API 文档,提供文档模板、认证方式、请求/响应格式 与基础 RESTful 规范。完整安全建议、多模块结构、变更记录、HTTP 状态码分类等高级功能需升级付费版。
---
slug: api-doc-writer-free
name: api-doc-writer-free
version: "1.0.0"
displayName: API文档编写器免费版
summary: 编写基础REST API文档,含模板、认证方式、请求响应格式与基础RESTful规范
license: MIT
description: |-
API 接口文档编写助手免费版。用于编写基础 REST API 文档,提供文档模板、认证方式、请求/响应格式
与基础 RESTful 规范。完整安全建议、多模块结构、变更记录、HTTP 状态码分类等高级功能需升级付费版。
tags:
- 研发工具
- Documentation
tools:
- read
- exec
---
# 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格式返回,包含操作状态(成功/失败)、处理摘要和具体输出数据。失败时返回错误码和错误信息,便于定位问题。
## 基础文档模板
### 文档头
```
版本：V1.0
更新日期：YYYY-MM-DD
维护人：XXX
```
### 通用说明
**认证方式**:
```
Authorization: Bearer <token>
```
**请求格式**:
```
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: 用户信息接口文档
**场景**: 为获取用户信息接口编写文档
**接口地址**:
```
GET /api/v1/users/{id}
```
**请求参数**:
| 参数名 | 类型 | 位置 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | long | path | 是 | 用户ID |
**请求示例**:
```
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: 创建用户接口文档
**场景**: 为创建用户接口编写文档
**接口地址**:
```
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 命名规范（名词复数、小写、连字符分隔、避免动词）。
## 已知限制
1. **无安全建议**: 不含加密传输、Token 过期、频率限制等安全规范
2. **无多模块结构**: 不支持用户/订单/支付等分模块文档组织
3. **无变更记录**: 不支持版本追踪与变更历史记录
4. **无 HTTP 状态码分类**: 不含 1xx-5xx 完整分类说明
5. **无分页参数规范**: 不含 page/page_size 默认值与最大值设置
6. **无错误示例**: 不提供每个接口的错误响应示例
---
> **升级付费版** 解锁: 完整安全建议、多模块结构、变更记录、HTTP 状态码分类、分页参数规范、URL 命名规范、错误示例编写等完整能力。
don't have the plugin yet? install it then click "run inline in claude" again.