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