为什么你不应该忽略内部API文档的重要性

您的内部团队构建并使用许多 Web 服务。其中一些可能是公共 API，例如用于电子商务的 BigCommerce 或用于交易电子邮件的 SendGrid。最开明的开发团队正在内部构建微服务。这些可重复使用的组件可以加快整个组织的开发速度。为了看到这些收益，您的工程师及其业务合作伙伴需要知道有哪些服务可用。

优秀的文档可让您的团队了解每个 API 的功能并快速上手。这是更大规模 API 设计管理流程的一个重要成果。实施后，您的内部 API 文档可为您的团队提供即时和长期价值。

如何帮助开发团队更快地构建API文档？

询问任何开发人员他们最讨厌的 API 文档，很可能与糟糕的文档有关。文档可能不准确、不完整，或者完全缺失。当然，这些事情不会是恶意发生的。即使是最基本的 API 文档也很难维护，尤其是当你在开发的同时记录许多 API（或微服务）时。

当您根据 OpenAPI描述生成文档时，您始终会在工程师开始编写代码之前获得更新的 API 参考。

当有机器可读的可靠来源时，构建 API 的工程师会更快地完成工作。例如，他们可以通过编程确认已构建哪些端点。此外，他们无需停下来编写文档。相反，他们可以生成文档的新版本。更好的是，构建这些参考文档可以纳入您的开发工作流程，从而自动完成。

使用内部 API 的开发人员也加快了他们的工作速度。他们可以在最终 API 准备就绪之前开始集成。有了最新、准确的 API 文档，您的团队可以自信地同时进行开发。

如何扩展你的API知识？

“API” 似乎是一个技术术语，但您希望软件流程对非工程师来说也易于理解。产品和业务团队成员对 API 越来越熟悉。此外，这些非程序员通常对您使用软件解决的问题有重要的了解。

有了大量的公共 API 示例，非工程师就习惯于查看文档。虽然他们不一定会编写代码来使用这些 API，但他们可以弄清楚它是如何工作的。您的内部文档提供了有关可能性的重要知识。让您的工程师免于开会过度，而是邀请您的 API 文档人员参加会议。

您的文档将根据那些在公共 API 开发经验方面投入大量精力的公司进行内部评判。您可能会发现您的 API 文档中缺少重要部分。其中一些仅在 API 构建后才需要，但其他一些可以在 API 开发过程中生成。

您的整个团队都可以从提前访问内部文档中受益。由于 API 可以解决业务问题，因此具有该业务知识的人员可以提供重要的反馈。例如，产品经理可能会发现某个端点未返回所需的数据。或者业务开发经理可以识别合作机会并开始长期工作以安排富有成效的整合。如果在 API 构建后创建文档，则进行重大更改可能为时已晚。

如何创建一种API设计与管理的文化？

文档包含有关 API 的决策的可视化，便于用户阅读。无论您是否支持设计优先 API，组织内都会有人设计您的 API。在这个重要的过程中，您需要将意见扩展到工程团队之外。此外，API 设计管理文化将有助于保持 API 的一致性，这将使组织中的每个人都受益。

要了解您的 API 设计，OpenAPI 文档是真相的来源。在包括 Swagger（催生了 OpenAPI 计划）在内的众多格式中，OpenAPI 拥有最广泛的行业支持。JSON 或 YAML 文档首先用于机器，但可用于生成文档。Stoplight Studio帮助团队设计、组织和共享他们的 API。

话虽如此，API 设计管理并不是单一的工具。您无法强制实施一刀切的方法，并让您的团队能够灵活地快速行动。例如，将 OpenAPI 文档存储在您自己的 GitHub 存储库中，但将它们拉入相关工具中以生成文档、构建模拟服务器并与不太可能探索代码存储库的团队成员共享。

模块化方法允许您使用Spectral之类的工具，这是一种开源 JSON linter，可帮助编纂 API 样式指南。API 设计的一致性成为其自身的隐式文档。通过声明规则以保持设计的一致性，确保您的 OpenAPI 文档完整且超越技术上的正确性。

API 设计管理文化将帮助您制作更好的 API，并极大地改善您的内部 API 文档。您的工程团队将行动更快，并允许整个组织进行更多协作。

出色的内部文档主要基于 OpenAPI 描述构建，使任何人都可以了解哪些 API 可用以及每个 API 的功能。

源文链接：Why You Shouldn’t Ignore Internal API Documentation