B2B 解决方案公司 ONDA 为什么要琢磨「好的」API 文档
说 API 文档要从 UX 视角来写，很多人可能觉得「API 文档又不给普通用户看?」。毕竟大家印象里，UX 说的是软件这类服务的用户体验。那 B2B 解决方案公司 ONDA 为什么选这条路?
ONDA 在机遇市场里做创新
先要理解 ONDA 的服务。从民宿到酒店，我们提供一系列帮住宿方便运营的解决方案，其中最典型的就是统一销售系统 ONDA HUB。
客房库存和价格一次性连通多个销售渠道，住宿方能「一键」把房卖到 Airbnb、Agoda 等好几个 OTA 上。简单说，就是住宿和销售平台之间的桥梁。为什么需要这种技术创新?
因为住宿和销售平台之间的事儿，还有不少在走线下流程;住宿方如果分别入驻各个平台，A 平台来了订单，还得手动去 B 平台改库存——操作不及时就双重预订了。
ONDA HUB 把这些麻烦消掉，用技术让时间和人力用在刀刃上。
统一销售系统连接的基础，就是 API 文档
统一销售系统主要分两块:渠道连接 + 住宿产品供应连接。目前已接入 4 万多个住宿产品(住宿方)，连通 40 多个销售渠道。
我所在的 PO(Product Owner，软件服务里负责产品规划和落地的角色)团队，目标是扩大统一销售系统的底层网络。为了供应更多住宿，我们对接外部供应商;为了卖得更好(虽然已经连通了国内外主要 OTA)，我们还在接入更多样的销售渠道。
这个过程的核心之一，就是 API 文档。 系统连接的工作从读懂 API 文档开始。
*这里简单说一下，API 是什么?
Application Programming Interface(应用程序接口)的缩写，让两个软件组件能互相通信的机制。它定义了用请求和响应来通信的方法，API 文档里写的就是如何构造这些请求和响应。(来源:AWS)
换句话说，API 是公司对公司(或部门对部门)交换数据的一扇门。
ONDA API 的核心，就是拿到住宿信息发给销售平台，然后把平台生成的订单再传回住宿方。所以住宿产品供应商或销售方与我们约定好怎么传数据，这套规则就写在 API 文档里。
问题是，读懂别人写的 API 文档并不容易。 有哪些 API、怎么运行、返回什么结果，这些规格(规范)每家公司都不一样。加上文档是英文和数字组成的，第一次看 API 文档的人会一头雾水。
于是最花时间的反而是解释 API 文档、传达上下文。双方为了理解这份文档，反复提问答疑，来来回回好几轮。
降低沟通成本的选择，Readme 和 OAS
所以要减少沟通成本、高效完成连接，文档的格式至关重要。用清晰的语言写文档，合作方能直接测试，这样不仅节省合作伙伴(对 ONDA 来说就是销售方和供应方)的资源，还能提前避免因沟通误差造成的问题。
试了很多工具后，我们最终选了 'Readme'。设计或开发 API 的朋友应该都知道。它不只是把 API 规格(规范)排版得好看，更关键的是合作方能直接在文档里测试，从而提升文档的可理解性。
打个比方，跟外国人描述泡菜汤的味道，光说「泡菜熬出来的汤，又辣又鲜」，对方很难懂——让他尝一口，马上就知道了。同样道理，比起从头到尾读复杂的 API 文档，不如直接在文档里调用(Request)并拿到响应(Response)。
当然刚开始用 Readme 时也遇到过困难。即便是同一行业，不同公司或系统用的术语也有细微差别，所以需要在响应(Response)的各个字段(Response Body)里标注说明和类型——但 Readme 提供的基础编辑器功能有限。
韩国第一大加密货币交易所 'Upbit' 似乎遇到过同样的问题，它选择在文档正文里用长段文字说明响应(Response)规格。但和「好案例」Airbnb 的方式比起来，还是有遗憾。
- 表格整理得很清楚，理解不难，但没有标出实际的响应(Response)部分，很难看出结构。
- 每个字段是什么、格式是什么、可能的值有哪些，都标出了示例——不用来回翻文档就能看懂。
两份文档的区别在于，是用 Readme 提供的基础编辑器，还是用 OAS(OpenAPI Specification)这套行业标准规格。
OAS 简单说就是描述 RESTful API(两个计算机系统通过互联网安全交换信息的接口)的标准。它最大的优点是用不依赖语言的 json 和 yaml 格式，所有服务都能用。(想详细了解的朋友看这里)
对我们来说，跟销售方或供应方对接 API 时遇到的开发者或 PM(Product Manager)就是客户——所以从好的 UX 角度出发，我们选择按 OAS 格式上传，让响应(Response)的各个字段一目了然。
为了做出好 API 文档，我们引入的工具
各家公司写 API 文档的方式和负责人可能不同，ONDA 是以 PO 为主来管理。因为 PO 是与供应方、销售方沟通的主体，跟内部开发协作时也需要明确的规范。
非开发者的 PO、PM 要按 OAS 格式做出好 API 文档，引入了哪些工具?
✔️ yaml
OAS 用的是不依赖开发语言的 yaml 和 json 格式。yaml 和 json 是数据传输时的格式规则——json 有 []、{} 这些符号，看起来稍显复杂。团队成员对开发有一定理解，选哪个都行，但为了不熟悉开发语言的人，我们选了更贴近人类阅读习惯的 yaml。
✔️ vscode
像 Swagger Editor 这种支持简易 OAS 编写的工具早就有了。但为了协作和更方便使用，除了写 OAS 之外还需要功能更强的工具——vscode 很合适。通过一些扩展插件(Extension)，即使不熟悉 OAS 语法的人也能尽量少踩坑。
✔️ github desktop
为了持续维护，协作最重要，所以我们把 OAS 编写的代码传到 github。熟悉开发的朋友会在 vscode 里用 CLI(Command line interface，命令行接口，用户输入文本命令，计算机也用字符串输出)。这个操作我们也下载了 GUI(Graphical User Interface，图形用户界面，把输入输出等功能用易懂的图标等图形表示)应用，更直观地编写和共享。
提问量减少 90% 以上
不只是标注规格，而是从产品视角改进了原有的 API 文档后，对接启动时不再需要详细讲解。即使有问题进来，我们也立刻反映到文档里，反复提问明显减少——和以前相比，问题量减少了 90% 以上。
当然，因为不用管理多份文档，又能解释得清楚，内部满意度也很高。
遗憾的是，跟一些还在用老系统的合作伙伴协作时，还会收到 PDF 格式的 API 文档。抛开工具和格式，把合作伙伴当作客户、从 UX 视角去交付什么样的文档，今后依然非常重要。毕竟我们跟合作伙伴对接得越快，网络扩张的速度就越快。
⚠️ 未经许可禁止转载与再分发。引用时请注明出处 ONDA。