身為程序員最討厭看到的代碼沒有註釋，自己的代碼卻討厭寫註釋，覺得麻煩，接口也是這樣。

比如公司要做一個H5活動的頁面，開發文檔已經發到後端開發、設計、與前端的郵箱了，其實這個時候就可以開始開發了。開發人員開始論證H5頁面中邏輯是否能夠實現，以及該邏輯的合理性，及時的反饋給產品進行修改或者優化。等一切都定下來的時候，各方面就可以開始動工了。

一般來說，設計資源會在後端接口開發完成之前給到。對於一個對開發工作足夠得心應手的後端工程師，一般看到設計稿，就知道接口的數據結構和內部的邏輯是怎麽樣的。因此不必等到接口真正開發完成，才給到前端同學。

這樣子前端同學和後端同學，均能並行開發。比如一個H5活動頁面需要原來需要1個星期來完成，現在只需要4天時間，節省的兩天，程序員就可以用來提升自己技能和用來休息了。

但是呢，人都是惰性的。開發的時候不願意寫文檔，尤其是接口文檔，覺得很麻煩。我的同事們，有時候也懶得寫接口文檔，前端同學根據接口返回的數據來進行開發，有時候接口返回數據出錯，前端並不知道正確的接口數據是什麽，就會發生耽誤開發時間，本來能夠如期完成工作，結果在對接接口方面花費了太多的時間。

在大量的接口開發工作中，我使用了很多文檔工具，如Markdown 工具（馬克飛象），另外一個就是ApiDoc文檔生成工具。markdown 語法大部分寫過程序的同學都知道，比較好用，適合寫個博客什麽的，可以把寫作的焦點放在內容上，而不是格式上。但是對於markdown 寫的接口文檔來講，可能就不太適用了。接口文檔需要豐富的格式來構建層次，還需要表格來裝載參數。當接口很多的時候，還需要將接口分類，還需要有檢索接口的功能。另外一個痛點就是，比如後端PHP開發同學寫了個markdown文檔，給到了前端同學，或者客戶端同學，還要提示他們如何使用。並不是每個人電腦都裝了markdown解析器。這樣子就很煩人了，還好ApiDoc 解決了這個棘手的問題。

用了很長時間，總結了ApiDoc 的幾個優點：

1、安裝簡便，傻瓜式安裝

2、接口文檔語法很簡單，不必增加記憶成本，寫接口文檔很輕松，不再耗費大量時間，而是順手復制粘貼

3、生成的文檔格式漂亮，並且實用，滿足了開發人員對接口的各種需求。

由於本文並不是講述ApiDoc 的教程文檔，說實在話，這類東西，還是官方的文檔最實用。參數那麽多，並不需要拿個小本本記下來，需要的時候，到官網上復制粘貼即可，用多了，自然常用的就會記下來。附一張ApiDoc 生成文檔的截圖：

用apiDoc簡化接口開發