身為程式設計師最討厭看到的**沒有注釋，自己的**卻討厭寫注釋，覺得麻煩，介面也是這樣。
比如公司要做乙個h5活動的頁面，開發文件已經發到後端開發、設計、與前端的郵箱了，其實這個時候就可以開始開發了。開發人員開始論證h5頁面中邏輯是否能夠實現，以及該邏輯的合理性，及時的反饋給產品進行修改或者優化。等一切都定下來的時候，各方面就可以開始動工了。
一般來說，設計資源會在後端介面開發完成之前給到。對於乙個對開發工作足夠得心應手的後端工程師，一般看到設計稿，就知道介面的資料結構和內部的邏輯是怎麼樣的。因此不必等到介面真正開發完成，才給到前端同學。
這樣子前端同學和後端同學，均能並行開發。比如乙個h5活動頁面需要原來需要1個星期來完成，現在只需要4天時間，節省的兩天，程式設計師就可以用來提公升自己技能和用來休息了。
但是呢，人都是惰性的。開發的時候不願意寫文件，尤其是介面文件，覺得很麻煩。我的同事們，有時候也懶得寫介面文件，前端同學根據介面返回的資料來進行開發，有時候介面返回資料出錯，前端並不知道正確的介面資料是什麼，就會發生耽誤開發時間，本來能夠如期完成工作，結果在對接介面方面花費了太多的時間。
在大量的介面開發工作中，我使用了很多文件工具，如markdown 工具（馬克飛象），另外乙個就是apidoc文件生成工具。markdown 語法大部分寫過程式的同學都知道，比較好用，適合寫個部落格什麼的，可以把寫作的焦點放在內容上，而不是格式上。但是對於markdown 寫的介面文件來講，可能就不太適用了。介面文件需要豐富的格式來構建層次，還需要**來裝載引數。當介面很多的時候，還需要將介面分類，還需要有檢索介面的功能。另外乙個痛點就是，比如後端php開發同學寫了個markdown文件，給到了前端同學，或者客戶端同學，還要提示他們如何使用。並不是每個人電腦都裝了markdown解析器。這樣子就很煩人了，還好apidoc 解決了這個棘手的問題。
用了很長時間，總結了apidoc 的幾個優點：
1、安裝簡便，傻瓜式安裝
2、介面文件語法很簡單，不必增加記憶成本，寫介面文件很輕鬆，不再耗費大量時間，而是順手複製貼上
3、生成的文件格式漂亮，並且實用，滿足了開發人員對介面的各種需求。
由於本文並不是講述apidoc 的教程文件，說實在話，這類東西，還是官方的文件最實用。引數那麼多，並不需要拿個小本本記下來，需要的時候，到官網上覆制貼上即可，用多了，自然常用的就會記下來。附一張apidoc 生成文件的截圖：
apidoc生成介面文件
e soft node node global node v v12.18.2 e soft node node global npm v 6.14.5 npm install apidoc g安裝之後進入node的node global目錄如下圖說明安裝完成 增加apidoc.json檔案到專案根...
編寫介面文件apidoc用法
一 使用 npm install apidoc g 三 在目錄裡面編寫注釋 api company list 獲取公司資訊testm apiname 獲取公司列表testd apigroup all apiversion 0.1.0 apidescription 介面詳細描述 apiparam pa...
介面文件生成工具 apidoc
apidoc在您的源 中通過建立api注釋從而生成api說明文件。我們以express的專案為例 1 建立apidoc.json 2 我們在routes資料夾下建立api資料夾，用於書寫介面注釋說明,例如 api news newscontent 新聞詳情 apiversion 1.0.0 apin...