简洁易读的API文档

语言: CN / TW / HK

开发API必然少不了编写API文档,API文档所涉及的点太多,在编写时不仅要考虑到文档的完整性,同时还需要考虑到文档的可读性。

完整性包括API的请求参数、响应结果、示例等等。API文档就像一份说明书,需要记录API的零件(API由什么构成),还需要记录API如何使用,并且使用时遇到的问题是否是正常的。

就像说明书一样,API文档会有不同的人查阅,这其中包括公司内部人员与外部用户,内部人员包括开发人员、测试人员、运维人员、运营等,而外部用户包括合作伙伴,一些云API还包含各种各样的需要使用云API的用户,例如地图API,需要面向企业开发者或者个人开发者、学生等。而这些用户的技术水平参差不齐,所以文档的可读性是API文档编写者需要特别注意的。

API文档工具

工具是API文档编写者的福音,一款好的API文档工具能减少API编写的工作量,并且优化团队的沟通效率。在这里推荐的是Eolinker,使用了也有两年了,从刚开始个人测试到后来的团队协作,一直在用这款工具。本文介绍一下该工具的API文档部分功能。

导入功能

在Eolinker可以对多个平台项目进行导入,该功能可以快速创建已有的项目。

API文档

除了导入,还可以在Eolinker添加新的API。在新增API界面,该工具提供了API所需内容的表单,把API信息填入表单后,即可查看API文档。

API文档界面可以看到该API的所有信息。还可以设置API变更通知,查看API版本与变更历史,对API进行评论等。

项目分享

项目分享有两类,一种是在线分享,一种是离线文档,可根据不同用户需要进行分享文档。

在线分享功能可以生成分享连接,在浏览器打开后可以实时查看到项目内API的进展。

离线文档支持多种格式导出,使用起来非常方便。

以上是Eolinker从创建API到分享API的简单介绍,从界面可以看出Eolinker所生成的API文档简洁、详细,功能也很全面。感兴趣或者需要使用管理工具管理API的,可以考虑使用看看。

使用地址:[www.eolinker.com( https://datayi.cn/w/4PK51zZ9)

分享到: