api-documentation-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Documentation Writer

API文档编写指南

Create comprehensive, developer-friendly API documentation.

生成全面、对开发者友好的API文档。

Instructions

操作说明

When a user needs API documentation:

Gather API Information:
- API type (REST, GraphQL, WebSocket, gRPC)?
- Authentication method (API key, OAuth, JWT)?
- Base URL and versioning strategy?
- Available endpoints and their purposes?
- Request/response formats?
- Rate limiting or usage restrictions?
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

Format Output (REST API example):

markdown

# [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):

json

{
  "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

POST /resource

Create a new resource.

Request Body:

json

{
  "name": "string (required)",
  "description": "string (optional)",
  "metadata": "object (optional)"
}

Request Example:

bash

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):

json

{
  "id": "124",
  "name": "My Resource",
  "description": "A test resource",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Handling

All errors follow this format:

json

{
  "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

Rate Limiting

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

status code.

Code Examples

JavaScript (Node.js)

javascript

const response = await fetch('https://api.example.com/v1/resource', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

Python

python

import requests

response = requests.get(
  'https://api.example.com/v1/resource',
  headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

Support

Documentation: https://docs.example.com
Support: support@example.com
Status: https://status.example.com

undefined

For GraphQL APIs, adapt to show:
- Schema definitions
- Query examples
- Mutation examples
- Subscription examples
- Variables and directives
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
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

当用户需要编写API文档时：

收集API信息:
- API类型（REST、GraphQL、WebSocket、gRPC）？
- 认证方式（API key、OAuth、JWT）？
- 基础URL和版本控制策略？
- 可用端点及其用途？
- 请求/响应格式？
- 速率限制或使用限制？
生成完整的文档结构:

概述部分:
- API的功能（1-2句话）
- 核心能力
- 快速入门清单
- 支持与资源
认证说明:
- 如何获取凭证
- 认证令牌的放置位置
- 已认证请求示例
- 令牌刷新流程（如适用）
基础URL与版本控制:
- 生产环境和沙箱环境URL
- 版本格式（路径、请求头、查询参数）
- 当前版本与更新日志链接
端点详情（每个端点需包含）:
- HTTP方法与路径
- 功能描述
- 路径参数
- 查询参数
- 请求头
- 请求体 schema
- 响应码及含义
- 响应体 schema
- 请求示例（curl、JavaScript、Python）
- 响应示例（格式化JSON）
错误处理:
- 标准错误响应格式
- 常见错误码及含义
- 故障排除指南
速率限制:
- 限制规则与时间窗口
- 需关注的请求头
- 如何处理速率限制错误
SDK与库:
- 官方客户端库
- 社区维护库
- 安装说明
Webhooks（如适用）:
- 可用的Webhook事件
- 配置流程
- 负载示例
- 安全验证

输出格式（REST API示例）:

markdown

# [API名称] 文档

## 概述

[API功能简要描述]

**基础URL**: `https://api.example.com/v1`

**认证方式**: 通过`Authorization`请求头传递API Key

## 快速入门

1. [步骤1]
2. [步骤2]
3. [步骤3]

## 认证说明

所有请求均需在`Authorization`请求头中携带API Key:

Authorization: Bearer YOUR_API_KEY


从[控制台链接]获取你的API Key。

## 端点详情

### 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）:

json

{
  "data": [
    {
      "id": "123",
      "name": "示例资源",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 100,
  "limit": 10,
  "offset": 0
}

响应码:

```
200
```
- 请求成功
```
400
```
- 请求参数错误
```
401
```
- 未授权（无效API Key）
```
429
```
- 超出速率限制
```
500
```
- 服务器内部错误

POST /resource

创建新资源。

请求体:

json

{
  "name": "字符串（必填）",
  "description": "字符串（可选）",
  "metadata": "对象（可选）"
}

请求示例:

bash

curl -X POST "https://api.example.com/v1/resource" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的资源",
    "description": "测试资源"
  }'

响应（201 Created）:

json

{
  "id": "124",
  "name": "我的资源",
  "description": "测试资源",
  "created_at": "2024-01-15T10:30:00Z"
}

错误处理

所有错误均遵循以下格式:

json

{
  "error": {
    "code": "invalid_request",
    "message": "'name'字段为必填项",
    "details": {
      "field": "name"
    }
  }
}

常见错误码:

```
invalid_request
```
- 请求格式错误
```
authentication_failed
```
- API Key无效
```
not_found
```
- 资源不存在
```
rate_limit_exceeded
```
- 请求次数过多
```
internal_error
```
- 服务器内部错误

速率限制

限制规则: 每小时最多1000次请求

相关请求头:

```
X-RateLimit-Limit
```
: 允许的总请求次数
```
X-RateLimit-Remaining
```
: 剩余可用请求次数
```
X-RateLimit-Reset
```
: 限制重置的时间戳

超出限制时，将收到

状态码。

代码示例

JavaScript (Node.js)

javascript

const response = await fetch('https://api.example.com/v1/resource', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

Python

python

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://status.example.com

undefined

针对GraphQL API，需调整为展示:
- Schema定义
- 查询示例
- 变更（Mutation）示例
- 订阅（Subscription）示例
- 变量与指令
文档编写最佳实践:
- 从可直接复制使用的示例开始
- 同时展示请求与响应
- 使用真实的示例数据
- 包含错误场景
- 解释每个参数的含义
- 提供多语言代码示例
- 使用统一的格式
- 尽可能添加“在线调试”交互式示例
- 关联相关端点
- 包含更新日志与版本说明
开发者体验优化建议:
- 包含“60秒快速入门”及可运行示例
- 提供Postman集合或OpenAPI规范
- 展示常见使用场景与工作流
- 包含故障排除章节
- 提供测试/沙箱环境
- 附带SDK及安装说明
- 提前说明速率限制细节
- 展示分页模式
- 解释过滤与排序选项

Example Triggers

示例触发场景

"Write API documentation for my REST endpoints"
"Create OpenAPI spec for my API"
"Document this GraphQL schema"
"Generate developer docs for my webhook API"
"Write authentication guide for API"

"为我的REST端点编写API文档"
"为我的API创建OpenAPI规范"
"编写这个GraphQL Schema的文档"
"为我的Webhook API生成开发者文档"
"编写API的认证指南"

Output Quality

输出质量要求

Ensure documentation:

Starts with working example
Explains every parameter and field
Shows realistic request/response examples
Includes error handling
Provides code samples in multiple languages
Uses consistent formatting
Is organized logically (most common operations first)
Includes authentication clearly
Covers edge cases and limitations
Follows REST/GraphQL best practices
Is scannable with good use of headers
Includes interactive examples when possible

Generate comprehensive, developer-friendly API documentation that makes integration effortless.

确保文档:

以可运行的示例开头
解释每个参数与字段
展示真实的请求/响应示例
包含错误处理内容
提供多语言代码示例
使用统一的格式
逻辑组织清晰（常用操作优先）
明确说明认证方式
涵盖边缘情况与限制
遵循REST/GraphQL最佳实践
结构清晰便于快速浏览
尽可能包含交互式示例

生成全面、对开发者友好的API文档，降低集成难度。