编写易读、可测试、可运行的API文档

Document

自从开放的API接口在社交媒体以及Web 2.0中运用的越来越广泛,API已经成为了互联网产品的标准配置。并且不光是对外提供API,对于前后端分离的应用,API也是非常重要的一部分。编写一个好的API,不光是代码写得好,最重要的是文档写得好。但是我们在写文档的时候尝尝会遇到下面几个问题:

  • 没有统一的编写规范,这样不同的人在维护的时候尝尝会导致文档越来越乱,最终无法继续维护,也无法阅读。
  • API修改以后,文档没有跟着改,或者改错了,导致API的使用者无法正常调用。
  • 作为前端开发,往往是在API开发完成以前,就要根据API的文档准备一些mock data来帮助开发,如果API文档可以直接生成一个mock server,就会非常方便

下面我们来看看如何构建能够解决以上问题的,完美的文档。