为何须要使用api文档

什么是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