作者：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 时预期的结果。API 规范的一个很好的例子是 OpenAPI 规范。您可以在 GitHub 上查看此规范的最新版本 (3.0.1)。
在某些方面，OpenAPI 3.0.1 文档也是 API 文档，但 API 规范解释了 API 的行为方式以及对 API 的期望。GitHub 上的 OpenAPI 规范文档正是这样做的。在文档中，有许多 API 对象、值和参数、如何调用这些对象以及每个对象的作用。我们还看到了对象之间的关系以及每个对象如何使用。
例如，如果您查看 请求体对象部分，您会找到有关此对象的作用、其固定字段的描述和类型以及请求体示例的信息。您将看到请求体对象应该如何工作以及使用此功能时的预期。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 定义可用于自动生成 API 文档、代码示例和 SDK。从 API 定义文件生成 API 文档（静态和交互式）的工具的几个示例是 SwaggerHub 和 Swagger Inspector。可以从 API 定义自动生成示例代码和 SDK 的工具的几个示例包括 REST United 和 SwaggerHub。
API 定义也可以导入到模拟服务器中以进行虚拟 API 测试。许多用于模拟服务器和 API 测试的工具都允许导入 API 定义文件，其中包括 SoapUI 和 SwaggerHub。
API 定义非常重要，因为它可以用来支持自动化工具，这些工具可以确保您的 API 成功，例如交互式文档和 SDK。一些开发人员甚至提倡模式优先 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 文章、培训、教程等内容的电子邮件。 订阅