API文档实践

好的API文档不是随意就可以生成的。它需要明确的指导方案、团队一致的努力、严格的用户评审以及在API的整个生命周期中维护文档。如果需要编写的好的API文档则应该包括：

必要的组件。完整的文档通常包含有参数说明、错误消息、响应信息、示例，以及全面的更改日志的部分。一些API文档还包括一系列指南，这些指南提供了API使用和用例的详细示例。

了解目标用户。为目标用户量身定制API文档。如果该文档是为新手开发人员准备的，需要专注于教程，示例和指南。如果文档是为有经验的开发人员准备的，则需要构建详细说明语法，参数，自变量和响应详细信息的参考资料。

分配文档职责。开发团队的一名或多名成员应开发和维护API文档，以确保文档的准确性，清晰性和易用性。好的API文档工具可以从单个人的创建、添加注释、示例和其他基本组件中获益。可以将此职责交给能使文档易于访问并且与其他部门（例如产品开发，市场）有合作的人员。

API文档的覆盖范围。语法参考、示例和指南创建了API文档的技术核心。例如，对于每个调用或请求，语法引用的长度应该大致相同，并且包含相同的元素。如果一个功能的详细信息超过五页，而另一个功能只有半页，则文档可能不完整。类似地，注意那些只显示一小部分API调用的示例，或者忽略了处理响应（如错误消息）的示例。

将文档带入开发过程。如果将API文档包含在迭代开发过程中，通常会更好。对于每个新版本，文档都应进行相应的更新和更改。将API文档作为事后思考或单独的任务来处理会导致API文档不全面。创建全面的API文档需要花费时间和精力，但是值得进行投资。缺少、不完整或不正确的API文档可能会使API管理变得困难。

演示工具：Eolinker
使用地址：

原文：https://www.cnblogs.com/dc20181010/p/14116521.html