作者：Janet Wagner
我们经常被问及 API 规范和 API 文档之间的区别。因此，今天我们打算概述一下 API 文档、API 规范和 API 定义之间的区别以及它们的重要性。
什么是 API 文档？
API 文档本质上是 API 的参考手册——它告诉 API 使用者如何使用 API。API 文档是供人类（通常是开发者）阅读和理解的。提供设计良好、全面且易于理解的文档对于确保开发者获得出色的 API 体验至关重要。而卓越的开发者体验（DX）意味着 API 更大的成功机会。如果开发者无法理解您的 API 文档，他们很可能会寻找另一个文档更好、更容易集成的 API。良好的文档还有助于缩短新 API 使用者的入门时间。如果开发者拥有使用您的 API 所需的所有信息，他们就不必向您的公司发送电子邮件、致电您的客服部门或在论坛中发帖寻求帮助。
出色的文档包含许多内容，此处无法一一列举。但构成出色API 文档的一些要素包括快速入门指南、教程以及交互式文档，以便开发者可以尝试 API 调用。有许多工具可用于生成和维护 API 文档。其中许多工具可以从 API 定义文件（稍后将在本文中详细介绍）自动生成静态和交互式 API 文档。
API 文档应提供每个调用的示例、每个参数的说明以及每个调用的响应。它应包含常用语言（如 Java、JavaScript、PHP 和 Python）的代码示例。文档应提供每个 API 请求的解释和错误消息示例。同样重要的是，API 文档应积极维护并始终保持最新。
什么是 API 规范？
API 规范是一个经常与 API 定义互换使用的术语。尽管这些术语有许多相似之处，但它们是不同的实体。API 规范提供了对 API 行为方式以及 API 如何与其他 API 链接的广泛理解。它解释了 API 的功能以及使用 API 时预期的结果。OpenAPI 规范就是一个很好的 API 规范示例。您可以在 GitHub 上查看此规范的最新版本 (3.0.1)。
在某些方面，OpenAPI 3.0.1 文档也是 API 文档，但 API 规范解释了 API 的行为方式以及对 API 的预期。GitHub 上的 OpenAPI 规范文档正是这样做的。该文档中有许多 API 对象、值和参数，以及如何调用这些对象以及每个对象的功能。我们还可以看到对象之间的关系以及每个对象的使用方式。
例如，如果您查看请求正文对象 (Request Body Object) 部分，您会找到有关此对象功能、其固定字段的描述和类型以及请求正文示例的信息。您将看到请求正文对象应如何工作以及使用此功能时的预期结果。API 规范还表明了 API 的设计方式以及 API 支持的数据类型。
OpenAPI（以前称为 Swagger 规范）是几种 API 规范语言之一。还有 RAML 和 API Blueprint。值得注意的是，这些 API 规范语言正趋向于融合为一种 API 规范语言，即 OpenAPI。
什么是 API 定义？
API 定义与 API 规范类似，因为它提供了对 API 组织方式和 API 功能的理解。但 API 定义旨在供机器消费，而不是供人类消费 API。API 定义以机器可读的格式提供有关 API 功能、如何与其他 API 链接以及预期结果的信息。它侧重于定义 API 并概述 API 的结构。
API 定义通常用作自动化工具的基线。API 定义可用于自动生成 API 文档、代码示例和 SDK。从 API 定义文件生成 API 文档（静态和交互式）的一些工具示例包括 SwaggerHub 和 Swagger Inspector。从 API 定义自动生成示例代码和 SDK 的一些工具示例包括 REST United 和 SwaggerHub。
API 定义也可以导入到模拟服务器中进行虚拟 API 测试。许多支持导入 API 定义文件的模拟服务器和 API 测试工具包括 SoapUI 和 SwaggerHub。
API 定义很重要，因为它可用于支持自动化工具，这些工具可以确保您的 API 成功，例如交互式文档和 SDK。一些开发者甚至提倡“Schema 优先”的 API 设计，这意味着首先基于一种规范语言创建 API 定义，然后编写 API 代码。
彼此关联，却又不同
API 文档、API 规范和 API 定义都彼此关联，但它们是不同的实体。它们各自都具有重要的作用。
文档告诉开发者和其他 API 使用者如何使用 API。毕竟，如果开发者不知道如何使用您的 API，您的 API 又怎能成功呢？
API 规范提供了对 API 功能和预期结果的广泛理解。该规范主要关注 API 的设计或您的设计理念。API 设计和功能是将 API 与应用程序集成时的关键因素。
最后，API 定义是关于机器消费 API，并提供机器可读的格式供自动化工具使用，例如自动化 API 文档和 SDK 生成器。
API 文档、API 规范和 API 定义都是 API 成功的关键。
感谢阅读！正在寻找更多 API 资源？订阅 Swagger 新闻通讯。每月接收包含我们最佳 API 文章、培训、教程等的电子邮件。订阅