什么是 API 文档？
API 文档是一份可交付的技术内容，其中蕴含无关如何无效应用和集成 API 的阐明。这也是一本简单明了的参考手册，编写了应用 API 所需的所有信息，以及无关性能、返回类型、参数等详细信息，并提供了教程和示例反对。
API 文档通常由惯例的内容创立和保护工具以及文本编辑器实现的。例如 Swagger、eolinker 标准之类的 API 形容格局曾经自动化了文档处理过程，从而使团队能够更轻松地生成和保护 API。
第三方开发人员是 API 的次要用户，正忙于解决简单的编程难题。API 是技术用户达到目标的一种伎俩，他们心愿尽快集成推动他们的软件开发，这意味着他们应该疾速理解你的 API 的价值和用处。开发人员在发现、学习应用并最终与 API 集成时所积攒的教训称为开发人员教训。API 文档是取得杰出开发人员教训的要害。
为什么要应用文档 API？
在 API 生命周期的所有阶段中，文档可能是增长最快的畛域。对于围绕文档的工具生态系统尤其如此。留神到这一趋势很乏味，因为从传统上讲，文档是开发人员在编写代码时很少关注的货色。实际上，实现代码比编写良好的文档要容易得多。
进步用户使用率
领有良好的 API 文档的一个重要起因是，它改善了开发人员应用 API 的体验，这与 API 的采纳间接相干。如果 API 文档正确无误，那么更多的人将很容易在提供的服务中发现价值，从而能够更好地倒退和采纳。
节俭反对工夫和老本
好的文档还能够缩小新用户（无论是外部开发人员还是内部合作伙伴）的培训工夫。蹩脚的文档或者没有文档意味着更多用户依赖于团队培训来了解如何应用 API。
相同，当你在用户应用 API 之前先试用 API，并且装备具体的 api 文档，将为团队节俭大量工夫来回复电子邮件和电话。
易于保护
文档可带来良好的产品保护。它能够帮忙外部团队理解资源、办法及其相干申请和响应的详细信息，从而能够更快地进行保护和更新。
结语
应用 API 时，文档是取得良好体验的要害。它不仅能进步用户满意度，还能够进步 API 的使用率。在提供优良的 API 文档的条件下，api 治理平台还反对测试、监控等性能，让用户在应用 API 方面取得杰出的体验。
原文：https://dzone.com/articles/wh…
翻译：www.eolinker.com