跳转到正文
API 101
本文目录

第 98 篇

如何为非开发人员编写 API 文档

要点

  • 非开发人员同样关心技术事实。 产品经理、分析师、安全审查人员、支持团队和合作伙伴都需要准确的说明,只是所需的细节层次不同。
  • 先讲结果和流程。 在介绍端点和载荷之前,先说明 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

图旁也要配上文字。明确“符合条件”“已批准”“已确认”和“已拒绝”各是什么意思。单靠图示难以满足无障碍需求,也往往讲不清策略的例外。

先解释概念,再介绍协议

有些技术术语是最准确的表达。只要有助于读者正确理解,就应保留并解释,而不是一律删去。

可以按以下顺序介绍:

  1. 通俗解释:“客户端会证明发起调用的是哪个应用。”
  2. 技术名称:“这叫应用身份认证。”
  3. 实现细节:“在这个示例中,生产 API 使用 OAuth 2.0 客户端凭据授权,适用于能妥善保护凭据的机密客户端,代表应用本身发起调用。”
  4. **参考链接:**为实现者提供令牌和权限范围的文档链接。

术语表既要解释技术,也要解释业务领域。“账户”“客户”“租户”和“工作区”看似可以互换,实际可能对应不同的归属和计费规则。为每个关键术语说明定义、不包含的范围、来源系统和相关概念。

避免使用未解释的缩写。首次出现时写出全称,之后统一用法。如果另取一个通俗名称会让字段对应关系变得模糊,就不要另取。例如,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 文档,了解如何在本地化时保留标识符和契约细节。

编辑本篇文章

获取方案