API 定义是结构化数据文件，提供有关 API 应该如何工作以及如何组织的关键信息。与为人类可读性而设计的 API 规范不同，这些文件旨在供机器可读。 API 定义通常包括请求格式要求、使用的协议以及端点的命名约定。由于文件本身只是结构化文本并且不能直接执行，因此它们可以使用任何编程语言。

如果使用得当，API 定义可以与现有的开发工具协同工作，以生成人类可读的文档、样板代码和测试用例等工件。请继续阅读，了解有关 API 定义如何工作以及如何将它们无缝集成到开发过程的任何阶段的更多信息。

API 定义：优点和工具

如果您以前没有使用过 API 定义，您可能会想知道为什么要费心——尤其是当创建它们会在开发过程中提前增加一些时间时。本节概述了创建 API 定义的主要好处，并讨论了一些流行的方法。

为什么要创建 API 定义？

创建 API 定义的一个简单原因是，为了与市场上的某些常见平台配合使用，可能有必要这样做。例如，如果您使用来自 Google Cloud、Azure、Apigee 或 Amazon 的 API 网关，则需要先准备好 API 定义，然后您的 API 才能在这些平台上上线。所有这四个平台都支持流行的OpenAPI 规范，我们将很快更深入地讨论该规范。

虽然与行业标准平台的兼容性是采用 API 定义的一个很好的理由，但这远不是唯一的原因。近年来，许多开发团队都采用了设计优先的方法。如果您的团队也在其中，那么 API 定义是理所当然的。它们不仅迫使您考虑 API 的预期设计和功能，而且还可以与许多自动化实现工具配合使用。

API 定义可以帮助完成的一些任务包括自动生成 SDK 和文档，以及用于测试接口的模拟服务器实例。通过这些用例，API 定义可以作为未来文档的参考点。

API 定义的另一个好处是它们可以帮助您相对较早地发现代码中的逻辑错误，特别是当您使用验证工具时。在这个阶段发现的错误比以后遇到的错误更容易纠正。 IBM 的一项研究表明，产品发布后发现的错误的修复成本是设计过程中发现的错误的四到五倍。

API 定义的一个不太明显但同样重要的好处是确保不同团队之间的设计方法保持一致。为现有代码添加 API 定义还提供了额外的好处，即减少开发人员在组织内更换团队时加快速度所需的时间，因为文档已经就位。

API 定义有哪些选项？

API 定义最常见的标准是前面提到的 OpenAPI 规范。鉴于其广泛采用，更详细地探讨这种方法是有意义的。

OpenAPI 背后的理念是在整个 API 生命周期中携带信息。由于文件通常是用 YAML 或 JSON 编写的，因此它们可以轻松地在使用不同框架和不同语言的代码库之间共享。这意味着您的 API 的使用者无需了解您选择的编程语言的详细信息即可使用该 API。

至少，OpenAPI 定义文件必须包含重要的详细信息，例如所使用的 OpenAPI 标准的版本、标识 API 的元数据（包括其名称、描述和版本）、相关服务器端点以及这些端点上允许的操作。 OpenAPI 规范还提供了有关服务器、安全系统、可重用对象、标签等信息的空间。正如结构化文本文件中的典型情况一样，信息可以根据需要嵌套在 API 定义中。

尽管 API 定义本身是文本文件，但这并不意味着您在创建它们时仅限于简单的文本编辑器。拥有方法的可视化模型以及语法检查和自动完成等强大的开发功能会很有帮助。 Stoplight Platform包括一个可视化编辑器，用于创建 OpenAPI 定义以及其他相关文件。 SoapUI是另一个工具，它允许您从 API 定义自动生成测试用例和模拟服务器等内容。

但是，您可能会遇到限制，这意味着 OpenAPI 不适合您的需求。好消息是您还有其他可能的选择。例如，如果您在 GraphQL 上投入了大量资金，则可以使用 JSON 或 GraphQL SDL 为其创建 API 定义。还存在适用于流行格式的工具，例如 MuleSoft 的 RAML 和 Google 的 protobuf。

API 定义在任何开发阶段都有帮助

理想情况下，与大多数设计方法一样，您希望在开发过程中尽早引入 API 定义。但这并不意味着如果您已经开始开发工作，或者即使您已经在市场上有产品，那么一切都会失败。本节提供有关如何合并 API 定义的建议，无论您处于开发过程的哪个阶段。

创建新的 API 设计优先和定义优先。

当谈到设计优先的方法时，我们倾向于考虑人类用户的需求，并且我们应该始终牢记它们。但许多代码交互永远不会到达人类，了解我们如何管理机器之间的通信非常重要。了解如何充分利用自动化工具是创建 API 定义的关键要素。

如果您已经拥有丰富的设计优先思维工作经验，或者您是那种喜欢深入研究的人，那么您可能会考虑模式优先设计。临时 API 设计的最大缺点之一是，只要 API 发生任何更改，无论是添加功能还是实施新服务器，都需要验证所有内容。手动进行这些更改是一个劳动密集型且容易出错的过程。通过在 API 定义中合并相同的信息，您可以使用自动化工具来为您处理这些更新。

在创建设计规范的同时创建定义文件甚至可以帮助您引出和完善系统需求。遵循 OpenAPI 规范等标准允许您以与平台和语言无关的方式执行此操作。

对阶段性成果保留进度凭证

即使您已经开始开发工作，API 定义仍然很有帮助。在这个特定阶段合并 API 定义的最重要的好处之一是，它可以帮助确定您已经编写的代码是否符合您希望继续构建产品的方式。如果事实果真如此，那就太好了！但即使您在此阶段发现代码中存在问题，现在修复它们也比在开发的后期阶段修复它们要容易得多。

幸运的是，有多种工具可以帮助您节省完成此任务的时间。 RedHat 的API Designer就是这样的工具之一，如果您已经在使用他们的 OpenShift 服务，那么它特别有用。另一个选择是 IBM 的API Connect ，它可以帮助您创建 REST 和 SOAP API 的定义。这两个工具都提供图形界面，并且可以根据 OpenAPI 规范创建定义。

从现有 API 创建定义。

虽然 API 定义确实最适合在设计过程中引入，但这并不意味着已经发布的 API 不能从定义中受益。如前所述，如果您希望您的 API 能够与最流行的 API 网关配合使用，则需要建立一个定义。

但即使您不打算在主要平台之一上部署 API，为 API 设置定义仍然是一个好主意。例如，如果您的目标是在公司范围内提高代码库的一致性，那么为现有 API 创建定义以确保它们符合您打算维护的代码标准是有意义的，如前所述。如果您的代码所在位置与您想要的位置之间存在差距，那么创建 API 定义可以帮助您推动开发朝着您希望的方向发展。 Spectral等工具可以帮助您确保您的定义符合 OpenAPI 要求和组织的内部设计目标。

原文链接：API Definition and Creation Best Practices