前后端分离的工作模式于今是非常流行了，前后端工作的对接，就离开不了API文档的辅助。

 

根据自己以往的工作经历，以及了解的一些资讯，API文档的建立，无非以下几种方式：

1. word文档模板

2. 第三方平台，类如postman、showdoc等

3. 框架内单独自定义一套绑定路由的结构，再解析成html页面

4. 在框架内每个路由的方法的注释块里按照规则写注释，再解析生成api文档

5. 框架内直接编辑markdown文件，再转换成html页面

 

根据自己的使用心得，发表一下个人看法。

1.word文档模板：

这是在第一家公司--富士康科技集团--接触到的，就是公司准备好了一个API文档的模板，每个api对应一个表格，在表格里填上对应的路径(path)，调用方式(method)、请求参数，返回数据结构等信息。对于刚开始新增api是ok的，当时测试工作和后端正好在不同城市，api文档可以起到很好的沟通作用。但对于后期维护，总要完善了一个接口，就要对应的去word文档里查找并修改，一旦后端没有或忘记更新了，随着时间过着越久，反而后面越容易把自己带到坑里去。

 

优点：前期工作少，拿个模板就可以开写了。

缺点：更新接口不是很方便。

 

2.第三方平台：

工作经历中有一家用到，无非就是把api信息录入到第三方平台，本人很是反感。尤其是需要像form表单一样一个个栏位填写，一个个接口的添加，简直是作践后端的时间价值。维护？简直是更乱，因为第三方平台需要登录账号，每多一小步，人发懒的概率就越大，时间久了，api文档不同步的概率和范围就更大更广。

 

工作中现在我一直用postman测试接口，所以postman是必用的工具。至于用它写api文档是否支持又是否方便，本人没有接触过，就不发表看法了。

showDoc是编辑markdown方式，对于添加API接口，撰写体验还是很不错的。但接口信息像postman一样一条条分开的，查找浏览不方便，维护一般首先就是要查找，所以维护体验也感觉很不好。所以以往有的公司，项目涉及到成员多批变迁时，就有那种同一个功能出现几个不同的api。因为新增接口信息可以避免去了解去确认此功能接口之前是否已经撰写过，人都有惰性，就干脆直接新增了接口文档记录，结果就自然导致同样接口的文档记录有两三条，文档就慢慢失去了原本的价值：辅助新员工快速了解功能和开展工作。

 

那什么时候考虑第三方平台呢？

有的第三方平台实现了接口功能实时监控及安全防护，就是有受到攻击或者接口挂掉的情况时，可以给你手机发短信通知你。如果你非常需要这个，那你就用吧。

 

优点：前期工作少，有可能带有接口安全防护和实时监控，避免因为接口挂掉带来利益损失。

缺点：不仅多了一步登录操作，而且大多产品设计的页面体验不好，不利于快速新增及更新文档，管理不好的话，容易失去文档的本身价值。

 

3.自定义绑定路由的结构：

这是我自己起的名字，可能不太准确。

大体实现方式就是，接口写好了并定好了路由，就在另外一个php文件针对每一条路由用php语言来定义好一个api文档所需要的信息。

例如如下：

$app->route("user/getlist")
    ->request(
        array(
            'page' => '1 //第几页',
            'page_size' => '10 //每页数据条数'
        )
    )
    ->method('post')
    ->response(
        array(
            'data' => array(
                'total_count' => '199 //总记录条数',
                'list' => array(
                    'username' => 'coderzhai //姓名',
                    'gender' => '1  //1-男 2-女'
                )
            )
        )
    )

然后自己再根据上述结构解析出对应数据展示在页面里。

 

优点：跟后端代码一起，文档更新及维护更方便。文档按功能划分、按区域划分、按版本划分、增加用户权限控制等实现比较方便。

缺点：由于以上代码是用php语言编写的，一旦遇上哪里少了括号或是逗号等php语法错误，就会造成文档页面无法浏览。还需要费时间的去找到问题的所在并及时修复它。接口路由不适宜用resource组合的，因为具体对应增删查改哪几个接口不好确定。

 

4.利用方法的注释块生成api文档

这种方式是了解apidoc时了解到的，就是按照规定的规则在接口方法的注释块里备注信息，类如如下：

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUs