api-documentation-writer by onewave-ai/claude-skills
npx skills add https://github.com/onewave-ai/claude-skills --skill api-documentation-writer创建全面、对开发者友好的 API 文档。
当用户需要 API 文档时:
* API 类型(REST、GraphQL、WebSocket、gRPC)?
* 认证方式(API 密钥、OAuth、JWT)?
* 基础 URL 和版本控制策略?
* 可用的端点及其用途?
* 请求/响应格式?
* 速率限制或使用限制?
2. 生成完整的文档结构 :
概述部分 :
* API 的功能(1-2 句话)
* 关键能力
* 快速入门清单
* 支持与资源
认证 :
* 如何获取凭证
* 在哪里包含认证令牌
* 认证请求示例
* 令牌刷新流程(如适用)
基础 URL 与版本控制:
* 生产环境和沙箱环境 URL
* 版本格式(路径、请求头、查询参数)
* 当前版本和更新日志链接
(针对每个端点):
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
* HTTP 方法和路径
* 功能描述
* 路径参数
* 查询参数
* 请求头
* 请求体模式
* 响应代码及其含义
* 响应体模式
* 请求示例(curl、JavaScript、Python)
* 响应示例(格式化的 JSON)
错误处理 :
* 标准错误响应格式
* 常见错误代码及其含义
* 故障排除指南
速率限制 :
* 限制和窗口期
* 需要检查的请求头
* 如何处理速率限制错误
SDK 与库:
* 官方客户端库
* 社区库
* 安装说明
Webhooks (如适用):
* 可用的 Webhook 事件
* 设置流程
* 负载示例
* 安全验证
3. 格式化输出 (REST API 示例):
# [API 名称] 文档
## 概述
[API 功能的简要描述]
**基础 URL**:`https://api.example.com/v1`
**认证**:通过 `Authorization` 请求头的 API 密钥
## 快速开始
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]
## 认证
所有请求都需要在 `Authorization` 请求头中包含 API 密钥:
Authorization: Bearer YOUR_API_KEY
从 [仪表板链接] 获取您的 API 密钥。
## 端点
### GET /resource
获取资源列表。
**参数**:
- `limit`(可选,整数):结果数量(最大 100,默认 10)
- `offset`(可选,整数):分页偏移量(默认 0)
- `filter`(可选,字符串):按字段筛选
**请求示例**:
```bash
curl -X GET "https://api.example.com/v1/resource?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
响应 (200 OK):
{
"data": [
{
"id": "123",
"name": "Example",
"created_at": "2024-01-15T10:00:00Z"
}
],
"total": 100,
"limit": 10,
"offset": 0
}
响应代码 :
* `200` \- 成功
* `400` \- 错误请求(参数无效)
* `401` \- 未授权(API 密钥无效)
* `429` \- 超出速率限制
* `500` \- 服务器错误
创建新资源。
请求体 :
{
"name": "string (必填)",
"description": "string (可选)",
"metadata": "object (可选)"
}
请求示例 :
curl -X POST "https://api.example.com/v1/resource" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Resource",
"description": "A test resource"
}'
响应 (201 Created):
{
"id": "124",
"name": "My Resource",
"description": "A test resource",
"created_at": "2024-01-15T10:30:00Z"
}
所有错误遵循以下格式:
{
"error": {
"code": "invalid_request",
"message": "字段 'name' 是必填项",
"details": {
"field": "name"
}
}
}
常见错误代码 :
* `invalid_request` \- 请求格式错误
* `authentication_failed` \- API 密钥无效
* `not_found` \- 资源不存在
* `rate_limit_exceeded` \- 请求过多
* `internal_error` \- 服务器错误
限制 :每小时 1000 次请求
请求头 :
* `X-RateLimit-Limit`:允许的总请求数
* `X-RateLimit-Remaining`:剩余的请求数
* `X-RateLimit-Reset`:限制重置的时间戳
当达到速率限制时,您将收到 429 状态码。
const response = await fetch('https://api.example.com/v1/resource', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
* 文档:<https://docs.example.com>
* 支持:[support@example.com](https://github.com/onewave-ai/claude-skills/blob/HEAD/api-documentation-writer/mailto:support@example.com)
* 状态:<https://status.example.com>
4. 对于 GraphQL API ,调整以展示:
* 模式定义
* 查询示例
* 变更示例
* 订阅示例
* 变量和指令
5. 文档最佳实践 :
* 从可运行的示例开始(可直接复制粘贴)
* 同时展示请求和响应
* 使用真实的示例数据
* 包含错误情况
* 解释每个参数
* 提供多种语言的代码示例
* 使用一致的格式
* 尽可能添加"试一试"交互式示例
* 链接相关端点
* 包含更新日志和版本控制信息
6. 开发者体验提示 :
* 包含一个"快速开始",提供 60 秒内可运行的示例
* 提供 Postman 集合或 OpenAPI 规范
* 展示常见用例和工作流程
* 包含故障排除部分
* 添加测试/沙箱环境
* 提供带有安装说明的 SDK
* 提前说明速率限制详情
* 展示分页模式
* 解释筛选和排序选项
确保文档:
生成全面、对开发者友好的 API 文档,使集成变得轻松。
每周安装量
88
代码仓库
GitHub 星标数
74
首次出现
2026年1月24日
安全审计
安装于
opencode73
codex73
gemini-cli71
cursor71
github-copilot68
kimi-cli64
Create comprehensive, developer-friendly API documentation.
When a user needs API documentation:
Gather API Information :
Generate Complete Documentation Structure :
Overview Section :
* What the API does (1-2 sentences)
* Key capabilities
* Getting started checklist
* Support and resources
Authentication :
* How to obtain credentials
* Where to include auth tokens
* Example authenticated request
* Token refresh process (if applicable)
Base URL & Versioning:
* Production and sandbox URLs
* Version format (path, header, query param)
* Current version and changelog link
Endpoints (for each endpoint):
* HTTP method and path
* Description of what it does
* Path parameters
* Query parameters
* Request headers
* Request body schema
* Response codes and meanings
* Response body schema
* Example request (curl, JavaScript, Python)
* Example response (formatted JSON)
Error Handling :
* Standard error response format
* Common error codes and meanings
* Troubleshooting guide
Rate Limiting :
* Limits and windows
* Headers to check
* How to handle rate limit errors
SDKs & Libraries:
* Official client libraries
* Community libraries
* Installation instructions
Webhooks (if applicable):
* Available webhook events
* Setup process
* Payload examples
* Security verification
3. Format Output (REST API example):
# [API Name] Documentation
## Overview
[Brief description of what the API does]
**Base URL**: `https://api.example.com/v1`
**Authentication**: API Key via `Authorization` header
## Quick Start
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Authentication
All requests require an API key in the `Authorization` header:
Authorization: Bearer YOUR_API_KEY
Get your API key from [dashboard link].
## Endpoints
### GET /resource
Retrieve a list of resources.
**Parameters**:
- `limit` (optional, integer): Number of results (max 100, default 10)
- `offset` (optional, integer): Pagination offset (default 0)
- `filter` (optional, string): Filter by field
**Request Example**:
```bash
curl -X GET "https://api.example.com/v1/resource?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
Response (200 OK):
{
"data": [
{
"id": "123",
"name": "Example",
"created_at": "2024-01-15T10:00:00Z"
}
],
"total": 100,
"limit": 10,
"offset": 0
}
Response Codes :
* `200` \- Success
* `400` \- Bad request (invalid parameters)
* `401` \- Unauthorized (invalid API key)
* `429` \- Rate limit exceeded
* `500` \- Server error
Create a new resource.
Request Body :
{
"name": "string (required)",
"description": "string (optional)",
"metadata": "object (optional)"
}
Request Example :
curl -X POST "https://api.example.com/v1/resource" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Resource",
"description": "A test resource"
}'
Response (201 Created):
{
"id": "124",
"name": "My Resource",
"description": "A test resource",
"created_at": "2024-01-15T10:30:00Z"
}
All errors follow this format:
{
"error": {
"code": "invalid_request",
"message": "The 'name' field is required",
"details": {
"field": "name"
}
}
}
Common Error Codes :
* `invalid_request` \- Malformed request
* `authentication_failed` \- Invalid API key
* `not_found` \- Resource doesn't exist
* `rate_limit_exceeded` \- Too many requests
* `internal_error` \- Server error
Limits : 1000 requests per hour
Headers :
* `X-RateLimit-Limit`: Total requests allowed
* `X-RateLimit-Remaining`: Requests remaining
* `X-RateLimit-Reset`: Timestamp when limit resets
When rate limited, you'll receive a 429 status code.
const response = await fetch('https://api.example.com/v1/resource', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
* Documentation: <https://docs.example.com>
* Support: [support@example.com](https://github.com/onewave-ai/claude-skills/blob/HEAD/api-documentation-writer/mailto:support@example.com)
* Status: <https://status.example.com>
4. For GraphQL APIs , adapt to show:
* Schema definitions
* Query examples
* Mutation examples
* Subscription examples
* Variables and directives
5. Documentation Best Practices :
* Start with working example (copy-paste ready)
* Show both request and response
* Use realistic example data
* Include error cases
* Explain every parameter
* Provide code examples in multiple languages
* Use consistent formatting
* Add "Try it" interactive examples when possible
* Link related endpoints
* Include changelog and versioning
6. Developer Experience Tips :
* Include a "Quick Start" with working example in 60 seconds
* Provide Postman collection or OpenAPI spec
* Show common use cases and workflows
* Include troubleshooting section
* Add testing/sandbox environment
* Provide SDKs with installation instructions
* Include rate limiting details upfront
* Show pagination patterns
* Explain filtering and sorting options
Ensure documentation:
Generate comprehensive, developer-friendly API documentation that makes integration effortless.
Weekly Installs
88
Repository
GitHub Stars
74
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode73
codex73
gemini-cli71
cursor71
github-copilot68
kimi-cli64
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
46,900 周安装