为什么你不应该忽略内部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 开发过程中生成。 Read more about 为什么你不应该忽略内部API文档的重要性[…]