第 98 篇
如何为非开发人员编写 API 文档
API7.ai
2026年07月21日
要点
- 非开发人员同样关心技术事实。 产品经理、分析师、安全审查人员、支持团队和合作伙伴都需要准确的说明,只是所需的细节层次不同。
- 先讲结果和流程。 在介绍端点和载荷之前,先说明 API 能做什么、谁参与、传输哪些数据,以及适用哪些规则。
- 让文档分层。 将业务概览、场景指南、数据与策略参考、开发者参考互相链接,让读者按需深入。
- 说明协议细节如何影响决策。 限流对应容量预期,权限范围对应访问边界,版本变更对应迁移承诺。
- 请目标读者参与审阅。 让 API 负责人核对技术事实,让实际读者验证文字是否好懂、能否指导决策。
还没开始写集成代码,API 就可能影响定价、合作伙伴接入、客户同意、运维、风险和支持。许多文档站却一上来就展示 curl、OAuth 权限范围和 JSON Schema。这些细节是实现集成所必需的,却无法回答其他读者带来的问题。
产品经理想知道 API 能否支持计划中的流程。合规审查人员需要确认哪些个人数据会跨越边界。运维团队要明确故障由谁负责、服务水平有何预期。合作伙伴经理则关心接入条件、审批步骤和商业限制。面向这些读者时,文档应保留准确的技术事实,并围绕他们要做的决策来组织。
明确读者及其决策
“业务用户”这个称呼太宽泛,无法指导写作。要具体列出读者群体、他们需要做的决定,以及所需的依据。
| 读者 | 典型决策 | 所需文档 |
|---|---|---|
| 产品经理 | API 能否支持某项客户流程? | 能力、限制、路线图状态、流程示例 |
| 业务分析师 | 系统和数据如何对应? | 领域定义、字段含义、业务规则、权威数据源 |
| 安全或合规审查人员 | 是否可以接受此集成? | 认证模式、数据分类、留存、可审计性、跨地域流向 |
| 合作伙伴经理 | 合作伙伴上线前需要完成什么? | 资质、接入阶段、沙盒访问、认证和支持 |
| 支持团队 | 故障由谁处理,可以检查什么? | 故障症状、状态信息、安全诊断方法、升级路径 |
| 运维负责人 | 应按什么可靠性和容量做规划? | 限制、依赖、服务目标、维护和事件处理流程 |
| 管理层发起人 | API 带来哪些价值和风险? | 业务结果、范围、采用情况指标、投入和责任归属 |
写作前,先访谈有代表性的读者。请他们讲讲最近做过的一项决定,或曾经遇到的一次误解。用实际任务来组织信息,比收集他们想要的栏目标题更有用。
为每个页面确定主要和次要读者。若一个页面同时试图讲透采购、数据语义和 Java 异常处理,往往很难服务好其中任何一类读者。
构建分层文档
面向非开发人员的文档不该只是端点参考的简写版。各层内容应该相互衔接,让读者按需深入:从结果和能力开始,依次了解业务场景、策略与数据、集成概念,最后再查阅端点、Schema 和可运行的代码示例。
1flowchart TB
2 O["Outcome and capability overview"] --> J["Business journey and use cases"]
3 J --> P["Policies, data, limits, and ownership"]
4 P --> I["Integration concepts and sequence"]
5 I --> R["Endpoint and schema reference"]
6 R --> C["Runnable code samples"]
7
8 O -. "Executive and product" .-> A1["Why and whether"]
9 P -. "Risk and operations" .-> A2["Rules and responsibility"]
10 R -. "Developers" .-> A3["How to implement"]
11
12 classDef overview fill:#e8f3ff,stroke:#1677ff,color:#102a43;
13 classDef policy fill:#fff7e6,stroke:#d48806,color:#5c3b00;
14 classDef detail fill:#f6ffed,stroke:#389e0d,color:#173b0b;
15 class O,J,A1 overview;
16 class P,I,A2 policy;
17 class R,C,A3 detail;从能力概览开始
用一页回答以下问题:
- API 对外提供什么业务能力?
- 谁提供 API,谁使用它?
- 支持哪些场景,明确不支持哪些场景?
- 哪些数据会被读取、创建或修改?
- API 是公开的、仅对合作伙伴开放,还是仅供内部使用?
- 适用哪些审批、费用和服务承诺?
- 如何尽快且安全地评估它?
避免使用无法对应到实际行为的宣传说法。“实时”需要说明预期延迟或交付时限;“安全”则应链接到具体的认证、授权、加密和审计措施。
说明业务流程
用一个具体场景串联参与者、前置条件、正常流程、备选路径和完成标准。例如,客户提出符合条件的退款申请后,由支持人员按规则审批,经合作伙伴门户提交给退款 API,再由支付系统处理。支付撤销得到确认或被拒绝后,API 将结果和追踪编号返回给门户,支持人员据此告知客户。退款成功的流程要等下游会计系统收到已确认的结果才算完成。
1sequenceDiagram
2 actor Customer
3 participant Support as Support Team
4 participant Portal as Partner Portal
5 participant API as Refund API
6 participant Payments as Payment System
7
8 Customer->>Support: Requests eligible refund
9 Support->>Portal: Reviews policy and approves request
10 Portal->>API: Submits refund with business reference
11 API->>Payments: Requests payment reversal
12 Payments-->>API: Confirms or rejects reversal
13 API-->>Portal: Returns outcome and trace reference
14 Portal-->>Support: Shows next action
15 Support-->>Customer: Communicates final status图旁也要配上文字。明确“符合条件”“已批准”“已确认”和“已拒绝”各是什么意思。单靠图示难以满足无障碍需求,也往往讲不清策略的例外。
先解释概念,再介绍协议
有些技术术语是最准确的表达。只要有助于读者正确理解,就应保留并解释,而不是一律删去。
可以按以下顺序介绍:
- 通俗解释:“客户端会证明发起调用的是哪个应用。”
- 技术名称:“这叫应用身份认证。”
- 实现细节:“在这个示例中,生产 API 使用 OAuth 2.0 客户端凭据授权,适用于能妥善保护凭据的机密客户端,代表应用本身发起调用。”
- **参考链接:**为实现者提供令牌和权限范围的文档链接。
术语表既要解释技术,也要解释业务领域。“账户”“客户”“租户”和“工作区”看似可以互换,实际可能对应不同的归属和计费规则。为每个关键术语说明定义、不包含的范围、来源系统和相关概念。
避免使用未解释的缩写。首次出现时写出全称,之后统一用法。如果另取一个通俗名称会让字段对应关系变得模糊,就不要另取。例如,API 使用 settlement_status,可以在数据字典里的“结算状态”旁标注这个标识符。
说明 API 机制对各方意味着什么
端点表并不是唯一能准确说明 API 的方式。解释机制带来的实际影响,同时链接到精确的参考资料。
数据与隐私
按业务含义和分类描述数据。对每个重要对象记录:
- 为何要处理这些数据;
- 权威来源和目的地;
- 是否包含个人、财务、健康或机密信息;
- 谁有权读取或修改;
- 留存和删除要求;
- 地域或租户边界;
- 审计和同意要求。
不要在没有适用范围和责任方的情况下承诺“合规”之类的法律结论。链接至已批准的政策、协议或评估,说明应向哪个团队咨询合规问题。
认证与授权
认证解决“调用者是谁”,授权解决“调用者能做什么”。接下来,把角色或权限范围对应到业务能力:
| 访问权限 | 业务含义 | 示例操作 |
|---|---|---|
orders:read | 查看获准账户的订单状态 | 支持人员查看订单履约情况 |
orders:write | 创建或更新订单 | 商务系统提交订单 |
refunds:approve | 在规则允许的范围内批准退款 | 获得授权的主管确认退款 |
说明职责分离、审批、凭据归属、轮换和退出流程。读者不一定需要了解如何交换令牌,但需要知道谁能授予访问权限,以及合作关系结束后如何处置这些权限。
限制与服务行为
用读者能拿来做规划的语言解释限流。“每分钟 600 次请求”还应说明是按账户、凭据、路由还是地域计算,预期流量形态是什么,是否允许短时突发,以及如何申请更多容量。
说明可用性、维护、恢复目标和依赖项,并直接链接到合同依据。不要把期望达到的目标与服务等级协议混为一谈。
版本与变更
对相关方而言,新版本意味着协调成本,也可能影响客户。概括变更内容和原因、需要采取行动的人、关键日期、兼容性及负责人。按如何维护多个 API 版本的文档所述,链接到详细的迁移指南。
用不依赖编程知识的示例
把请求和响应解释为系统之间传递的数据,非开发人员也能从中受益。用一个短示例,在代码块外说明它的业务含义:
1{
2 "order_id": "ord_123",
3 "customer_reference": "crm-case-456",
4 "status": "confirmed",
5 "total": {
6 "currency": "USD",
7 "amount": "49.90"
8 }
9}order_id 由订单服务分配,customer_reference 将交易与支持工单关联,status 是取值受控的生命周期字段,金额用字符串表示是为了保留小数精度。这样,分析师不必先学 JSON 语法就能核对映射关系。
在讨论数据映射时,可提供合成记录供下载,附上字段定义、是否可选、允许值和敏感性分类。说明样例只用于演示,并非完整 Schema。
对比和检查清单适合用表格,关系和顺序适合用图示,理由和例外则适合用正文。为传递信息的图像和图表提供等效文字;纯装饰图像可按无障碍规范处理。WCAG 2.2 要求内容可感知、可理解,例如为非文本内容提供适当的文字替代,并让程序能识别页面语言。
按角色提供入口,复用同一份事实
开发者门户可以提供“评估 API”“规划安全审查”“接入合作伙伴”和“开始集成”等入口。这些路径最终应指向同一套受维护的定义和策略。
别把同一条限制复制到五个按角色划分的页面。对于支持地域、生命周期状态或限流档位等必须一致的事实,维护结构化的源内容或可复用片段,并为每一项指定负责人和审查周期。
搜索应同时识别业务用语和技术标识符。通过同义词,让搜索“采购”“订单”或 order_id 的读者找到相应概念,同时在页面中解释三者的准确区别。
API 管理平台也能提供运行上下文。例如,API7 Enterprise集中管理网关路由、策略及流量可见性。文档应把运行配置整理成经过审批的 API 目录,列出有哪些 API、谁负责、谁可使用,以及当前所处的生命周期阶段。运行时发现的内部或敏感服务不能自动对门户的广泛受众公开。
建立跨职能审阅流程
API 负责人可以核实技术事实,但无法代表每类读者。建议请以下人员参与:
- 产品或领域负责人核对能力和术语;
- 工程师核对契约和实际行为;
- 安全、隐私或法务人员审核相关主张;
- 支持或运维人员核对诊断和升级路径;
- 至少一名目标读者验证任务是否说清楚;
- 内容负责人检查结构、文字、无障碍和一致性。
请试读者完成一项具体任务,例如判断合作伙伴是否有资格接入、确认共享哪些数据,或找到交易失败后的负责人。只问“写得清楚吗?”很难得到有用的证据。
记录已做的决定和仍未解决的问题。如果服务目标尚未确定,直接说明并列出负责人,避免用模糊措辞掩盖不确定性。
面向非开发人员的文档检查清单
- 每个页面是否对应具体的读者及其决策?
- 概览是否说明能力、排除范围、访问权限和归属?
- 工作流程是否说明参与者、前置条件、例外和结果?
- 业务术语是否有定义,并对应技术标识符?
- 数据分类、访问权限、留存和地域流向是否清晰可见?
- 是否说明限制和可靠性对规划的影响?
- 业务说明是否链接到具体的技术参考?
- 图示是否配有文字,页面是否可用键盘和辅助技术访问?
- 是否有代表性读者用这份文档完成过实际任务?
- 每项受维护的事实是否有来源、负责人和审查日期?
总结
API 文档服务的是整个组织。先弄清读者要做什么决定,再按层次组织内容、保留准确的术语,并说明 API 机制如何影响工作流程、策略和责任归属,团队才有共同的规划和交付依据。
下一篇关注跨语言和地域的读者。阅读如何为全球读者翻译 API 文档,了解如何在本地化时保留标识符和契约细节。