第 91 篇
如何写出清晰简洁的 API 文档
API7.ai
2026年05月21日
要点
- 围绕具体任务和受众编写。 评估人员、首次集成的开发者、熟练用户和支持团队,需要从不同入口获取一致的技术信息。
- 展示完整、真实的行为。 将请求与有代表性的成功、错误响应配对,同时说明前提、限制及后续操作。
- 方便快速查阅。 用明确的小标题、短段落、参数表、一致的术语和分层细节,帮助读者迅速定位答案。
- 保持内容一致。 命名、身份认证、分页、错误格式和示例风格应有统一约定。
- 随 API 一起维护文档。 同时审查契约和文档的变更,测试示例,并用用户反馈和运行数据发现偏差。
开发者集成 API 时,需要不断查阅文档。清晰、完整、容易导航的文档可以缩短集成时间,减少错误和支持请求。本文介绍如何让 API 文档既能带读者入门,也能作为可靠的参考。
API 文档质量为什么重要?
文档难懂,设计完善的 API 也可能难以推广。开发者评估多个方案时,往往会把文档是否容易理解作为选择条件。
好的文档能降低使用过程各阶段的成本:
- 评估:用明确的示例帮助开发者快速判断是否适合。
- 入门:用分步指南缩短团队开始使用的时间。
- 集成:提供完整的端点参考,减少试错。
- 排障:解释错误码,降低对人工支持的依赖。
- 扩展使用:让读者能自行发现和理解高级功能。
可从集成耗时、支持成本和采用率等维度观察文档不足带来的影响。改进文档的目标,是让开发者更快完成任务。
1flowchart LR
2 E["Evaluate the API"] --> O["Onboard and authenticate"]
3 O --> I["Implement a use case"]
4 I --> T["Troubleshoot failures"]
5 T --> A["Adopt advanced capabilities"]
6 G["Clear, task-based documentation"] --> E
7 G --> O
8 G --> I
9 G --> T
10 G --> A
11
12 classDef journey fill:#f6ffed,stroke:#389e0d,color:#173b0b;
13 classDef docs fill:#e8f3ff,stroke:#1677ff,color:#102a43;
14 class E,O,I,T,A journey;
15 class G docs;编写有效 API 文档的原则
面向实际读者
不同读者有不同需求:
- 首次评估者需要快速入门和清楚的用途说明。
- 集成开发者需要完整的端点参考和身份认证流程。
- 熟练用户需要高级指南和性能优化建议。
- 支持工程师需要排障指南和错误参考表。
为初学者提供入门指南,为集成提供详细参考,为熟练读者保留进阶主题。
用示例说明实际行为
代码示例是开发者理解 API 的重要途径。为端点提供:
- 请求示例,展示必填参数和可选参数。
- 响应示例,使用贴近实际的数据,如具体值而不是
"string"占位符。 - 错误示例,展示常见的失败情况。
- 多种常用语言的代码片段。
下面对比两种写法。
信息不足的示例
1GET /users/{id}
2Returns a user object.
信息更完整的示例
1# Get user by ID
2curl https://api.example.com/v1/users/12345 \
3 -H "Authorization: Bearer YOUR_API_KEY"200 OK 响应体:
1{
2 "id": "12345",
3 "email": "developer@example.com",
4 "name": "Jane Developer",
5 "created_at": "2024-01-15T10:30:00Z",
6 "status": "active",
7 "role": "admin"
8}404 Not Found 响应体:
1{
2 "error": "user_not_found",
3 "message": "No user found with ID 12345",
4 "request_id": "req_abc123"
5}第二个示例展示了请求语法、真实感更强的响应结构以及失败表现。这里的命令和输出用于说明文档写法。
统一文档约定
统一约定能减少理解成本:
- 命名:响应使用
snake_case时,就在相同约定下持续使用它。 - 参数顺序:先说明身份认证,再列必填参数,最后列可选参数。
- 响应结构:不同端点沿用统一的响应包装格式。
- 错误格式:统一错误码、消息和附加上下文。
- 代码风格:保持缩进、引号和格式一致。
读者了解一个端点后,就更容易推断其他端点的基本写法。
便于扫读
开发者通常直接查找答案。编写时可以:
- 用明确的标题说明每一节涵盖什么。
- 把参数、返回值等关键信息放在前面。
- 用表格呈现参数和状态码等结构化信息。
- 用加粗标出关键术语和值。
- 将段落控制在 2–4 句左右。
- 用列表列举要点,避免把它们堆进一个长段落。
持续更新
代码和文档不一致时,开发者可能花费数小时追查本不该发生的问题。可以:
- 将文档与代码一同放在版本控制中。
- 要求代码变更与对应文档在同一拉取请求里提交。
- 从代码注解自动生成参考文档。
- 在代码审查时同时检查文档。
- 在 CI 中验证代码示例,发现破坏性变更。
API 文档的结构
清晰的结构让读者能从初步了解逐步走到进阶实现。
1. 概览和入门
概览应回答:
- API 能做什么? 用一段话概括用途。
- 适合谁使用? 说明主要场景和目标开发者。
- 需要准备什么? 说明账号、API 密钥和技术要求。
- 怎样最快发出有效请求? 给出步骤尽量少的快速入门。
示例结构如下。
1## Overview
2
3The Example User API enables user profile management and access control for web and mobile applications. It is designed for developers who need a consistent user model across several clients.
4
5## Quick Start
6
7Get your first API response in under 5 minutes:
8
91. Create a sandbox account in the Example developer portal and copy a test API key
102. Make your first request:
11
12curl https://api.example.com/v1/users/me \
13 -H "Authorization: Bearer YOUR_API_KEY"
14
153. See the full authentication guide for production setup2. 身份认证和授权
身份认证通常是集成的第一步。明确说明:
- 身份认证方式,例如 API 密钥、OAuth 2.0 或 JWT。
- 如何获取凭据,包括生成密钥的位置和 OAuth 流程。
- 如何传递凭据,包括适用的请求头格式、查询参数或请求体。
- Token 生命周期,包括到期、刷新和吊销。
- 作用域和权限,说明不同凭据可以访问什么。
示例如下。
1## Authentication
2
3All API requests require authentication using API keys passed in the `Authorization` header:
4
5Authorization: Bearer YOUR_API_KEY
6
7### Obtaining an API Key
8
91. Log in to the Example developer portal
102. Navigate to Settings > API Keys
113. Click "Generate New Key"
124. Copy the key (it will only be shown once)
135. Store the key securely (we recommend environment variables)
14
15### Key Security
16
17- Never commit API keys to version control
18- Rotate keys according to your organization's credential policy and immediately after suspected exposure
19- Use different keys for development and production
20- Revoke compromised keys immediately in the dashboard
21
22### Testing Authentication
23
24curl https://api.example.com/v1/auth/verify \
25 -H "Authorization: Bearer YOUR_API_KEY"
26
27# Success response
28{"valid": true, "scopes": ["read", "write"]}
3. 核心概念
复杂 API 应先介绍基础概念,再展开端点细节:
- 数据模型,例如用户、项目和 Webhook。
- 对象关系,说明各对象如何关联。
- 工作流,介绍常见的多步流程。
- 限制,包括速率限制、分页和数据大小约束。
理解这些概念后,读者更容易读懂端点文档。
4. 端点参考
每个端点可以按下列顺序记录。
端点概述
1## Create User
2
3`POST /v1/users`
4
5Creates a new user account with the provided information.
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string | 是 | 用户邮箱地址,必须唯一 | |
| name | string | 是 | 姓名,长度为 2–100 个字符 |
| role | string | 否 | 用户角色,可为 admin、member、viewer,默认为 member |
| metadata | object | 否 | 应用使用的自定义键值对 |
服务端必须检查调用方是否有权为新用户分配所请求的角色。例如,只有具备相应权限的调用方才能指定 role=admin。
请求示例
1curl -X POST https://api.example.com/v1/users \
2 -H "Authorization: Bearer YOUR_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "email": "new.user@example.com",
6 "name": "New User",
7 "role": "member",
8 "metadata": {
9 "department": "engineering",
10 "hire_date": "2024-01-15"
11 }
12 }'
响应示例
1{
2 "id": "usr_abc123",
3 "email": "new.user@example.com",
4 "name": "New User",
5 "role": "member",
6 "created_at": "2024-01-15T10:30:00Z",
7 "metadata": {
8 "department": "engineering",
9 "hire_date": "2024-01-15"
10 }
11}状态码
| 状态码 | 说明 |
|---|---|
| 201 | 创建用户成功 |
| 400 | 请求无效,例如缺少必填字段或邮箱格式不正确 |
| 401 | 身份认证失败 |
| 409 | 邮箱已存在 |
| 429 | 超出速率限制 |
错误示例
1{
2 "error": "validation_failed",
3 "message": "Email address is already registered",
4 "field": "email",
5 "request_id": "req_xyz789"
6}5. 错误处理
把共用的错误处理说明集中起来,减少重复:
- 错误响应格式,各类错误沿用一致的结构。
- 错误码,列出可能出现的应用错误码。
- HTTP 状态码,解释每个状态码在该 API 中的含义。
- 重试指引,说明哪些错误可以重试以及重试策略。
- 支持信息,说明联系支持人员时应提供哪些上下文。
下例是错误文档的结构示意。实际重试还要结合操作的幂等性、服务端提示与 API 契约。
1## Error Handling
2
3All errors return a consistent JSON structure:
4
5```json
6{
7 "error": "error_code",
8 "message": "Human-readable error description",
9 "field": "parameter_name",
10 "request_id": "req_abc123"
11}
12```
13
14**Field descriptions:**
15
16- `field`: Only present for validation errors, indicates which parameter failed
17- `request_id`: Include this when contacting support for faster troubleshooting
18
19### Common Error Codes
20
21| Code | HTTP Status | Description | Retry? |
22| --- | --- | --- | --- |
23| invalid_request | 400 | Missing or invalid parameters | No |
24| authentication_failed | 401 | Invalid or expired API key | No |
25| insufficient_permissions | 403 | API key lacks required scope | No |
26| resource_not_found | 404 | Requested resource doesn't exist | No |
27| rate_limit_exceeded | 429 | Too many requests | Only if retry-safe; honor Retry-After when provided |
28| internal_server_error | 500 | Server error | Only if retry-safe; use bounded backoff |
29
6. 指南和教程
参考文档说明 API 提供什么,指南则解释怎样做以及为什么这样做。适合写成教程的内容包括:
- 常见工作流,例如多步骤的用户注册流程。
- 集成模式,例如 Webhook、轮询和批量操作。
- 按语言编写的指南,例如符合 Python、JavaScript 或 Go 惯例的实现。
- 典型场景演练,从头到尾展示一个用例。
1## Tutorial: Implementing User Registration
2
3This guide walks through implementing a complete user registration flow with email verification.
4
5### Step 1: Create User Account
6
7POST /v1/users with email and name. This creates an unverified account and triggers a verification email.
8
9### Step 2: Handle Verification Webhook
10
11Your webhook endpoint receives a `user.verified` event when the user clicks the email link.
12
13### Step 3: Update User Permissions
14
15Once verified, use PATCH /v1/users/{id} to grant full access.
16
写作风格建议
用主动语态。 写“发送 POST 请求”,让读者一眼看出要做什么。
用直接的指令。 写“在请求头中加入 API 密钥”,减少无用的前缀。
准确使用术语。 “参数”“字段”和“实参”有各自的含义,不宜混用来指同一个概念。
少用行话和习语。 面向不同语言背景的读者,表达要清楚。
测试示例。 可运行的代码示例应尽量做到只需替换凭据等明确的环境参数,就能复制运行。
提供有用的链接。 链接到相关端点、指南和外部资料,帮助读者继续查找信息。
维护文档
文档需要持续维护:
- 保留版本,覆盖所有受支持的 API 版本。
- 维护变更日志,记录破坏性和非破坏性变更。
- 提前说明弃用,并提供迁移指南。
- 建立反馈渠道,让开发者方便地报告文档问题。
- 分析使用情况,了解哪些页面访问量高,读者在哪些步骤离开。
可以采用文档即代码的工作流程。
1flowchart LR
2 C["API or contract change"] --> D["Documentation update"]
3 D --> R["Technical and editorial review"]
4 R --> V["Link, schema, and sample validation"]
5 V --> P["Publish with the API release"]
6 P --> M["Measure search, errors, and feedback"]
7 M --> B["Prioritized documentation backlog"]
8 B --> D
9
10 classDef gate fill:#fff7e6,stroke:#d48806,color:#5c3b00;
11 classDef publish fill:#f6ffed,stroke:#389e0d,color:#173b0b;
12 class R,V gate;
13 class P,M publish;1# Example: Test code examples in CI
2documentation-tests:
3 runs-on: ubuntu-latest
4 steps:
5 - uses: actions/checkout@v6
6
7 - name: Extract code examples
8 run: python scripts/extract_code_samples.py
9
10 - name: Run examples
11 run: |
12 for example in examples/*.sh; do
13 bash "$example"
14 done
总结
清楚的文档帮助开发者理解 API 并顺利集成。统一结构、提供完整示例并持续维护,可以让文档真正支持 API 的采用。需要进一步了解写作和示例格式时,可参考 Google 开发者文档风格指南。
从使用最多的端点开始,补充完整示例、清楚的参数说明和贴近实际的错误文档,再逐步覆盖其他端点。结构稳定后,可以比较生成 API 文档的工具,把适合重复执行的工作交给工具,同时保留编辑审查。