文档站：五分钟跑通第一个请求与错误自查

开发者不会读完文档，只会试到第一次成功。

一、注册之后，他花了四十分钟才发出第一个请求

周屿做了一个把钱包签名验证封装成 HTTP 接口的服务。文档首页用六层架构图解释请求如何穿过网关、鉴权、计费、队列、签名校验和回调，写得像一篇设计说明。他请做独立游戏的朋友陈墨试用。陈墨注册后先读架构，再找「快速开始」，发现它藏在「指南 → 进阶 → 接入流程」三级目录下；复制示例时，示例里的 key 是 YOUR_API_KEY，返回体是 {"ok": true, "data": {...}} 这样的伪代码。

以下情境为教学假设，人物、引语和数字不代表经核实的真实案例。

陈墨先在错误的位置填了真实 key，拿到 401；换到 header 里，又因为示例没写 Content-Type 吃到 415；第四次请求触发限流，返回 429 而文档没有解释。四十分钟后他关掉页面，给周屿发了一条消息：「等你们有沙箱再说。」周屿后来复盘，文档一共 46 页，但没有一页能让一个新用户在五分钟内看到 2xx。

问题不是文档不够多，是验收指标错了。周屿把「页数、覆盖率、架构讲清楚」当成完成标准，而开发者只关心一件事：从注册到看见第一个 2xx 要多久。这个时间可测、可定目标，也能写进每次文档发布的检查表。

把「第一次成功」写成指标。 文档首页第一屏只放三样东西：一句话说明产品解决什么问题、一个进入沙箱的按钮、一段可以直接复制的请求。架构图挪到「概念」里，给已经跑通的人看。衡量方式就是 TTFHW（Time To First Hello World），也就是首个 2xx 响应时刻减去注册时刻；它比「文档页数」更能预测客户会不会留下来。

二、五步内的 quickstart

quickstart 的目标不是讲清楚，而是让请求先跑通。控制在五步内，每一步都有一个可以直接复制的块，且每个块都不含占位符。步骤、产出与失败时的兜底写法如下。

五步各自对应一个可复制块，复制完就能执行，不需要读者替换任何字段：

POST https://api.example.com/v1/sandbox/keys

export API_KEY=test_9f2c41d8

curl -sS https://api.example.com/v1/verify -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"payload":"demo"}'

{"request_id":"req_7c1e","valid":true,"latency_ms":42}

下一步：/docs/errors、/docs/webhooks、/docs/sdk

同一屏上要并排放错误示例与成功示例，让读者能逐项对照，而不是读完整页再猜自己错在哪。

三、每个端点页的六块内容

端点页是开发者停留最久的地方。六块内容固定顺序，缺一块就会在工单里补回来。

1. 用途一句话：这个端点做什么、什么时候用、什么时候不该用，不写「本接口用于」这类空话。
2. 请求参数表：分路径、查询、请求体三组，每个字段都写必填、类型、默认值、取值范围与示例值。
3. 成功响应：真实字段、类型、是否可能为 null，并给一个完整但不冗长的示例。
4. 错误响应：每个可能的状态码与业务码，逐条写触发条件与处理建议。
5. 速率与配额：每秒与每分钟限制、超限返回什么、是否可重试、退避建议。
6. 可复制示例：curl 一条，主流语言各一条，示例里的 key 用 test_ 沙箱值。

参数表的标准只有一个：读者填错时，能在这张表里找到原因。

六块之外的第七块是变更记录。 每个端点页底部挂一段 changelog，只写与这个端点有关的字段增删、类型变化和默认值调整，并链到对应的迁移说明。读者不需要订阅整站更新，也能知道自己用的端点最近有没有动过。

示例要能整段复制。 示例里的域名、路径、header 与 key 前缀必须自洽，原样粘贴就能跑通；多语言示例共享同一个响应，避免读者切换语言后发现字段名不一样。

四、搜索、版本化与错误自查

文档站能不能被搜到，决定了它在关键时刻有没有用。搜索、版本与错误索引是一套东西的三个面。

搜索命中率。 搜索要能用错误码、字段名和中文口语三种方式命中。给每个端点配三到五个别名，比如「签名校验」「verify」「钱包验证」指向同一页。内部抽 20 个真实提问测试，至少 16 个第一次搜索就落到正确页面，命中率低于 80% 就先补别名，而不是继续写新文章。

版本化。 文档版本与 API 版本一一对应，/v1 的页面顶部标清版本，默认打开最新稳定版，同时允许开发者锁定旧版本。站点只保留最近两个大版本；旧版本页挂弃用横幅，写清下线日期与迁移链接。版本选择器要出现在每一页，而不是只在首页。

错误码索引页。 索引必须双向可查：按 HTTP 状态码查、按业务码查。每条包含含义、常见原因、自查三步、是否可重试，以及对应的文档锚点。

常见错误的自查清单。 401 查 key 前缀与 header 名，415 查 Content-Type，422 查枚举与长度，429 查并发与配额，5xx 记下 request_id 并给状态页链接。每条自查都要能在 30 秒内执行完，否则读者会直接开工单。

多语言文档至少覆盖 quickstart 与认证两页。 这两页决定第一次成功，其余页面可以先机翻并标注「以英文为准」。翻译范围与术语表由本地化流程决定，本文只负责指出先翻哪几页。

五、行动清单与复算验收

• 用秒表实测 3 位新用户从注册到首个 2xx 的时间，记下中位数
• 把 quickstart 压到 5 步以内，删掉所有占位符
• 给每个可复制块配一条能直接拿到沙箱 key 的路径
• 端点页按六块模板补齐，参数表写全必填、类型、默认值与范围
• 建错误码索引页，状态码与业务码双向可查
• 给 quickstart 与认证页各做一个非英语版本
• 抽 20 个真实提问测搜索命中率，低于 80% 就补别名
• 把 TTFHW 中位数与 P90 写进文档发布检查表

验收标准：TTFHW 中位数低于 5 分钟、quickstart 不超过 5 步且至少 3 个可复制块、错误自查覆盖率达到 100%。 任何一项不达标，文档就不算可发布。

TTFHW（首次成功时间）= 首个 2xx 响应时刻 − 注册时刻
示例：中位数 4 分 20 秒、P90 11 分；目标中位数 < 5 分钟
quickstart 步骤数 ≤ 5，可复制块数 ≥ 3
文档错误自查覆盖率 = 有错误示例的端点 ÷ 端点总数
示例：38 ÷ 38 = 100%

使用边界与实操验收

本文讲文档站的结构与首次成功验收，不涉及文档如何从代码注解生成，也不涉及多语言文案怎么翻。前者见 API文档自动化：OpenAPI规范与Swagger实战指南 ，它讲文档生成工具链，本文讲 quickstart 结构与首次成功验收。后者见 翻译工作流：机翻、审校与术语表 ，它讲多语言文案与术语表，本文只讲文档站要翻哪几页。

文中的 TTFHW 数值、步骤上限与覆盖率都是教学假设，不是行业基准。真实数值要用你自己的用户测，样本至少 3 人；单人产品的 P90 波动很大，建议每月复测一次并记在同一张表里。

验收以实测记录和工单为准。如果 TTFHW 已达标，工单里却仍反复出现 401，说明错误自查没写到点上，回到第四节重写索引，而不是继续加文档页数。

关键参考与核验范围

本文的 TTFHW 数值、步骤上限与覆盖率均为教学演示。核验日期：2026-10-25。

• OpenAPI Specification ：端点、参数与响应 schema 的规范来源，可作为端点页六块内容的结构底稿。
• Stripe Docs ：行业里被广泛参考的文档站组织方式，尤其是 quickstart、错误码索引与沙箱 key 的做法。

上述两条用于说明结构与行业惯例，不构成对任何产品或工具的推荐；具体页面与条款在本次核验中未逐条比对，故只给站点入口。

系列导航

• 上一篇：SDK 与示例：薄封装边界、版本策略与多语言维护成本
• 下一篇：版本与弃用：兼容窗口、弃用公告与迁移指南
• 回到目录：一个人把 API 做成产品：对外接口、开发者体验与支持
• 相关阅读：API文档自动化：OpenAPI规范与Swagger实战指南 、翻译工作流：机翻、审校与术语表