第 97 篇
如何在 API 文档中提供代码示例
API7.ai
2026年07月21日
要点速览
- 围绕开发者任务设计示例。 用一段简短、可运行的代码走通从认证到实际结果的流程,比给每个方法配一段互不相干的代码更有用。
- 同时展示原始 HTTP 请求和选定语言的惯用写法。 原始请求揭示契约,语言示例则说明开发者如何在熟悉的生态里安全地使用 API。
- 写清前置条件和占位符。 说明运行环境、SDK 版本、权限、测试数据、预期输出以及清理步骤。
- 按代码可能被带入生产来编写示例。 安全处理凭据,设置超时并检查状态;按场景落实有限重试和幂等。
- 持续测试示例。 语法检查只是起点。重要示例应在受控环境中运行,并验证有意义的响应。
代码示例往往是从理解 API 到信任 API 的最短路径。一个好示例能让开发者迅速看懂认证、URL 结构、序列化和响应处理。坏示例造成的影响也很直接:它可能让不安全的凭据用法看起来合理,忽略失败,使用过时的 SDK,或因为缺少配置说明而根本无法运行。
目标不是尽可能多地增加语言选项卡,而是为每类读者提供尽量小而完整的示例,教会正确用法,并随着 API 演进保持准确。
规划不同层次的代码示例
先从任务出发,再考虑端点。单个端点的代码片段适合查阅,但开发者要完成的任务往往跨越多个端点:获取凭据、创建资源、保存 ID、查询状态、处理失败,以及清理测试数据。
可以把示例分成三层:
- 请求片段展示一个操作实际发送的请求。
- 任务示例组合少量调用,完成一件事,例如创建并确认订单。
- 示例应用用端到端场景说明架构、配置、回调、持久化、可观测性和部署。
1flowchart TB
2 R["Request snippets"] --> T["Task-focused examples"]
3 T --> A["End-to-end sample applications"]
4 R -. "Precise contract" .-> V["API reference"]
5 T -. "Fast learning" .-> Q["Quick starts and guides"]
6 A -. "Production patterns" .-> C["Architecture tutorials"]
7
8 classDef small fill:#e8f3ff,stroke:#1677ff,color:#102a43;
9 classDef medium fill:#fff7e6,stroke:#d48806,color:#5c3b00;
10 classDef large fill:#f6ffed,stroke:#389e0d,color:#173b0b;
11 class R,V small;
12 class T,Q medium;
13 class A,C large;参考用户和支持数据来决定覆盖哪些语言。通常应提供用 curl 表达的原始 HTTP 请求,方便读者看清 SDK 抽象之下的请求头和消息体。再根据实际用户选语言,无需覆盖生成器能输出的每一种。少量经过审阅、符合语言惯用法的示例,比十二份机械转换后逐渐失准的代码更可靠。
为每个示例记录负责人、API 版本、语言及依赖版本、测试环境、最近一次验证时间,以及停用条件。维护者据此可以判断哪些示例需要更新。
让每个示例具备独立使用的上下文
在代码块前,立即说明:
- 示例要完成的任务;
- 所需账户、权限和测试资源;
- 运行环境及依赖版本;
- 要设置的环境变量或配置;
- 目标是沙盒还是生产环境;
- 调用可能创建、修改或删除什么。
在代码块后展示预期输出,并解释最关键的几行。如果输出包含会变化的 ID 或时间戳,把它们明确标成示例,避免让读者以为每次都会得到相同的值。
Google 开发者文档风格指南建议先介绍示例,再遵循相应语言的风格并保持排版清晰。需要省略代码时,应使用该语言的注释标明,不要用含义不清的省略号。这样读者就能区分可运行的代码和用于说明的片段。
使用一看就懂的占位符
占位符应让开发者知道要替换什么。ACCESS_TOKEN、ORDER_ID 和 API_BASE_URL 比 xxx、<foo> 或没有解释的样例值更清楚。还要说明这些值从哪里获取。
以下请求需要 curl 7.76.0 或更高版本,以支持 --fail-with-body。sandbox.example.com 是占位域名;请换成获准使用的 HTTPS 沙盒,填入有相应读取权限的测试令牌,并使用该沙盒中存在的测试订单 ID。示例通过环境变量提供凭据:
1export API_BASE_URL='https://sandbox.example.com'
2export ACCESS_TOKEN='replace-with-a-sandbox-token'
3
4curl --fail-with-body --silent --show-error \
5 --request GET "${API_BASE_URL}/orders/ord_123" \
6 --header "Authorization: Bearer ${ACCESS_TOKEN}" \
7 --header 'Accept: application/json'示例明确标出了令牌占位符,无需在源代码或提交到版本库的配置里粘贴真实密钥。生产文档还应链接到凭据轮换和最小权限指南。
截图和输出中不要使用真实的客户记录、电子邮件地址、API 密钥或生产资源 ID。合成数据应足够贴近实际,能说明 Schema,又要让读者看得出它是虚构的。
先展示契约,再引入抽象
原始 HTTP 请求可以回答几个关键问题:使用哪个方法、如何选择版本、需要哪些请求头、网络上发送的 JSON 是什么,以及哪个状态码代表成功。即使推荐用 SDK 集成,也应提供这层信息。
接着展示 SDK 或标准库的惯用写法。不要逐行照搬 curl,而应采用该语言常用的资源管理和错误处理方式。
以下 Node.js 22 示例使用内置 fetch,检查必需配置,设置超时,核对响应状态,并保留请求 ID 供支持团队排查。运行前设置获准的沙盒 URL 和对应测试令牌,确认该环境允许创建测试订单:
1const apiBaseUrl = process.env.API_BASE_URL ?? 'https://sandbox.example.com';
2const accessToken = process.env.ACCESS_TOKEN;
3
4if (!accessToken) {
5 throw new Error('Set ACCESS_TOKEN to a sandbox API token.');
6}
7
8const idempotencyKey = `docs-${crypto.randomUUID()}`;
9
10async function createOrder(key) {
11 const response = await fetch(`${apiBaseUrl}/orders`, {
12 method: 'POST',
13 signal: AbortSignal.timeout(10_000),
14 headers: {
15 Authorization: `Bearer ${accessToken}`,
16 'Content-Type': 'application/json',
17 'Idempotency-Key': key,
18 },
19 body: JSON.stringify({
20 customer_id: 'cus_123',
21 items: [{ sku: 'mug-blue', quantity: 2 }],
22 }),
23 });
24
25 const contentType = response.headers.get('content-type') ?? '';
26 const rawBody = await response.text();
27 let body;
28
29 if (contentType.includes('json')) {
30 try {
31 body = JSON.parse(rawBody);
32 } catch {
33 body = undefined;
34 }
35 }
36
37 if (!response.ok) {
38 const requestId = response.headers.get('x-request-id') ?? 'unknown';
39 throw new Error(
40 `Order creation failed (${response.status}, request ${requestId}): ` +
41 `${body?.title ?? 'Non-JSON or invalid error response'}`,
42 );
43 }
44
45 if (!body) {
46 throw new Error(
47 `Expected a JSON response but received ${contentType || 'no content type'}.`,
48 );
49 }
50
51 return body;
52}
53
54createOrder(idempotencyKey)
55 .then((order) => console.log(`Created order ${order.id}`))
56 .catch((error) => {
57 console.error(error.message);
58 process.exitCode = 1;
59 });这个示例比 fetch(url).then(r => r.json()) 多展示了实际集成所需的处理。它不自动重试,因为重试是否安全取决于操作和提供方的策略。像示例一样,每项逻辑操作只生成一次幂等键;如需重试,每次都应沿用同一个键。超时后若不知道前次请求是否成功,改用新键可能造成重复订单。相关指南还应说明键的保留时间及冲突处理规则。
兼顾完整性与重点
示例应能运行,或清楚标明它只是片段。参考文档可以省略应用脚手架,但要让读者看出省略了什么。快速入门则应提供导入、配置、入口和依赖安装步骤。
把主流程放在显眼的位置。可复用的日志逻辑或测试夹具可以移到链接指向的文件,避免让读者翻过 100 行准备代码才看到 API 调用。如果刻意省去某项生产要求,就写清楚,例如:“为便于说明,本示例使用内存存储;生产应用需要持久化存储和并发控制。”
既展示成功,也教开发者处理失败
至少说明语言或 SDK 如何提供以下信息:
- 状态码和响应头;
- 结构化错误响应体;
- 网络故障和超时;
- 认证失败;
- 限流和
Retry-After; - 幂等或冲突响应。
不要用一个丢弃细节的通用异常处理块包住所有错误。也不要把可能含有个人数据的完整生产响应打印出来。应展示 API 契约承诺的稳定字段,具体做法见编写 API 错误响应文档的最佳实践。
以下 Python 3.12 示例展示如何在不依赖 SDK 的情况下限制重试。运行前安装兼容的 requests(在独立的依赖文件中固定版本),并设置获准使用的沙盒 URL、令牌和测试订单 ID。
1import os
2import random
3import re
4import time
5
6import requests
7
8API_BASE_URL = os.getenv("API_BASE_URL", "https://sandbox.example.com")
9ACCESS_TOKEN = os.environ["ACCESS_TOKEN"]
10MAX_RETRY_DELAY_SECONDS = 30
11
12
13def get_order(order_id: str, max_attempts: int = 3) -> dict:
14 """Fetch an order and retry only documented transient responses."""
15 for attempt in range(1, max_attempts + 1):
16 response = requests.get(
17 f"{API_BASE_URL}/orders/{order_id}",
18 headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
19 timeout=(3.05, 10),
20 )
21
22 if response.status_code == 200:
23 if "application/json" not in response.headers.get("Content-Type", ""):
24 raise RuntimeError("Expected an application/json response")
25 return response.json()
26
27 if response.status_code not in {429, 503} or attempt == max_attempts:
28 response.raise_for_status()
29 raise RuntimeError(f"Unexpected HTTP status {response.status_code}")
30
31 retry_after = response.headers.get("Retry-After")
32 if retry_after is None:
33 delay = min(2 ** (attempt - 1), MAX_RETRY_DELAY_SECONDS)
34 elif re.fullmatch(r"[0-9]+", retry_after):
35 digits = retry_after.lstrip("0") or "0"
36 if len(digits) > len(str(MAX_RETRY_DELAY_SECONDS)):
37 response.raise_for_status()
38 delay = int(digits)
39 if delay > MAX_RETRY_DELAY_SECONDS:
40 response.raise_for_status()
41 else:
42 response.raise_for_status()
43
44 jitter = random.uniform(0, min(0.25, MAX_RETRY_DELAY_SECONDS - delay))
45 time.sleep(delay + jitter)
46
47 raise RuntimeError("unreachable")
48
49
50print(get_order("ord_123"))根据 RFC 9110,Retry-After 可以是非负十进制整数秒,也可以是 HTTP 日期。示例 API 的契约只接受前者。缺少响应头时用退避间隔;响应头不符合该示例契约,或者服务端要求等待的时间超出单次等待预算时,结束本轮自动重试,避免提前发出下一次请求。该示例仅对契约列出的暂时性 HTTP 响应重试,网络异常会交给调用方处理。
生成示例后仍要审阅
可以从 OpenAPI 文档批量生成请求片段和 SDK 调用。对于方法、URL、参数和基础消息体等可以从契约直接推导的内容,生成很有用。生成结果仍需要人工审阅。
自动生成的示例常有以下问题:
- 占位值不符合 Schema;
- 直接放入凭据或指向生产服务器;
- 缺少必要的配置和导入;
- 使用已弃用的库或方法;
- 忽略非成功响应;
- 代码不符合语言惯用法;
- 为所有可选字段生成代码,淹没常见用法。
把机械性的部分交给生成器,再应用由各语言负责人维护的模板和测试。将生成文件视为只读,并在契约变化时重新生成。手工改动会在下次构建时消失。
像测试产品代码一样测试示例
测试深度应与示例的重要程度相称。可以按以下顺序逐层验证:
1flowchart LR
2 S["Source sample"] --> F["Format and parse"]
3 F --> T["Type-check or compile"]
4 T --> M["Run with mock contract"]
5 M --> X["Run against sandbox"]
6 X --> A["Assert documented outcome"]
7 A --> P["Publish with verification date"]
8
9 classDef check fill:#fff7e6,stroke:#d48806,color:#5c3b00;
10 classDef ready fill:#f6ffed,stroke:#389e0d,color:#173b0b;
11 class F,T,M,X,A check;
12 class P ready;先检查格式和语法,再按语言做类型检查或编译;用遵循契约的模拟服务验证后,再到沙盒运行并断言文档承诺的结果。通过后,发布并记录验证日期。
可以把文档中的代码提取到临时文件;更好的办法是从源文件引入代码,让测试和展示使用同一份产物。解析 JSON 和 YAML 示例,编译静态类型语言的示例,检查脚本,并在结果可预测的沙盒中执行任务示例。
断言要覆盖示例真正想教的内容。进程退出码为零并不够,API 可能返回了不符合预期的空列表。应检查状态码、Schema 和关键值。隔离或清理新建资源,避免定时测试污染沙盒。
通过 CI 的密钥存储提供有效期短、权限受限的凭据。对日志脱敏,避免来自不可信 fork 的 PR 获取密钥。如果实际执行成本太高或会造成破坏,可以在每次变更时运行基于契约的模拟测试,再安排受控的端到端验证。
发现示例与实现的偏差
每个示例应关联 API 版本;适用时也应关联 SDK 版本。API 契约、SDK、网关路由或认证流程变更时,触发相关测试。发布前,在仓库中排查旧主机名、弃用路径和旧包名。
用元数据或报告向维护者提供最近验证信息。“昨天测试通过”的标记只有在测试覆盖真实场景、结果受到监控时才有意义。
安全地提供网关示例
网关文档应区分调用方发送的请求与管理员执行的配置。访问某条路由的客户端不需要知道上游主机名。配置 Apache APISIX 的运维人员则需要单独的示例,说明配置前置条件、权限受限的管理凭据和变更对流量的影响。
不要发布真实的 Admin API 密钥。使用环境变量和非生产端点。涉及路由、认证或限流的变更,应包含验证请求和回滚步骤。运维示例和应用代码应遵循相同的安全标准。
代码示例审阅清单
- 示例是否解决了读者的实际任务?
- 示例是原始 HTTP、语言惯用写法,还是完整应用?边界是否明确?
- 是否记录了前置条件、版本、权限、占位符和副作用?
- 读者复制后,是否能找出所有需要替换的值?
- 是否安全加载密钥,并使用合成数据?
- 超时、错误、重试和幂等是否遵守契约?
- 预期输出是否与示例及当前 Schema 一致?
- 省略的内容是否都已明确标注?
- 自动化流程是否解析、编译或执行了读者看到的那份代码?
- 是否有负责人,以及更新或停用的触发条件?
小结
好的 API 代码示例能把一条可靠的集成路径讲清楚,让开发者很快上手。选好场景,展示底层 HTTP 契约,用对应语言的惯用写法处理失败,并持续测试读者看到的那份代码。
下一篇如何为非开发人员编写 API 文档将拓宽读者范围,介绍如何解释 API 能做什么、会产生什么影响,而无需每位读者都亲自实现请求。