跳转到正文
API 101
本文目录

第 91 篇

如何写出清晰简洁的 API 文档

要点

  • 围绕具体任务和受众编写。 评估人员、首次集成的开发者、熟练用户和支持团队,需要从不同入口获取一致的技术信息。
  • 展示完整、真实的行为。 将请求与有代表性的成功、错误响应配对,同时说明前提、限制及后续操作。
  • 方便快速查阅。 用明确的小标题、短段落、参数表、一致的术语和分层细节,帮助读者迅速定位答案。
  • 保持内容一致。 命名、身份认证、分页、错误格式和示例风格应有统一约定。
  • 随 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 setup

2. 身份认证和授权

身份认证通常是集成的第一步。明确说明:

  • 身份认证方式,例如 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.

请求参数

参数类型必填说明
emailstring是用户邮箱地址,必须唯一
namestring是姓名,长度为 2–100 个字符
rolestring否用户角色,可为 admin、member、viewer,默认为 member
metadataobject否应用使用的自定义键值对

服务端必须检查调用方是否有权为新用户分配所请求的角色。例如,只有具备相应权限的调用方才能指定 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 文档的工具,把适合重复执行的工作交给工具,同时保留编辑审查。

编辑本篇文章

获取方案