最近公司開發項目需要前后端分離，這樣話就設計到后端接口設計。復雜功能需要提供各種各樣的接口供前端調用，因此編寫API文檔非常有必要了
網上查了很多資料，發現基於Markdown編寫文檔是一種比較流行而且成熟的方案了，話不多說，我也搞一搞試試。
電腦操作系統：deepin深度 Linux64位，比較難用的一個系統，但是公司強制使用，沒辦法
1、這里我用到了gitbook，GitBook 是一個基於 Node.js 的命令行工具，支持 Markdown 和 AsciiDoc 兩種語法格式，可以輸出 HTML、PDF、eBook 等格式的電子書。關於更多介紹可以參考：http://www.chengweiyang.cn/gitbook/introduction/README.html 。安裝gitbook可以直接使用命令： npm install gitbook-cli -g 來進行安裝。 當然前提是安裝了nodejs ，因為我們前端項目用的vue，加載依賴也需要nodejs，所以我已經提前裝好了直接使用。安裝nodejs可以參考：https://www.cnblogs.com/liuqi/p/6483317.html（非常贊）
執行完上面命令以后，可能需要設置軟連 nodejs中的gitbook ：ln -s /opt/nodejs/bin/gitbook /usr/local/bin/gitbook ，然后執行gitbook -V 來查看版本，首次會自動安裝gitbook。
2、安裝好gitbook以后，你就可以新建一個目錄，mybook ，然后進去直選命令兩個命令：gitbook init ， gitbook serve。 gitbook init命令是初始化你的書籍，會自動生成兩個文件，SUMMARY.md可以理解為整個書籍的目錄。如下圖：
然后繼續直行gitbook serve 就會根據SUMMARY.md來編譯書籍 如下：
然后就可以通過 http://localhost:4000/ 地址訪問啦。
提示：我剛安裝好gitbook以后是執行不到 “gitbook” 這個命令的，可以通過創建軟鏈接 解決，root權限下，執行 ： ln -s /opt/nodejs/bin/gitbook /usr/local/bin ，然后退出root就可以執行 gitbook命令啦，可以通過gitbook -V來查看版本
3、gitbook准備就緒，然后你還需要一個編輯工具，編輯工具應該有很多，我找到了一個是 Typora ，用了一下感覺還是比較好用，以后有機會再用其他的吧。 Typora安裝可以參考官網，https://www.typora.io/#linux ，安裝也非常簡單。
執行以下命令：
# or run: # sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys BA300B7755AFCFAE wget -qO - https://typora.io/linux/public-key.asc | sudo apt-key add - # add Typora's repository sudo add-apt-repository 'deb https://typora.io/linux ./' sudo apt-get update # install typora sudo apt-get install typora
需要注意的是 add-apt-repository 這個命令是需要安裝一個python包的， 直接執行：apt-get install python-software-properties 安裝完成以后應該就可以執行了。如果還是不行，可以自行google或者百度一下
4、Typora 安裝好以后，就可以用它打開文檔進行編輯了，去mybook目錄下，執行 typora SUMMARY.md 就可以進行編輯啦 ，然后下面就是SUMMARY的內容，使用 markdown語法進行編輯就可以了。
# Summary * [前言](README.md) * [一、登錄模塊](Chapter1/README.md) * [登錄接口](Chapter1/登錄接口.md) * [登錄發送短信](Chapter1/登錄發送短信.md) * [提交短信&支付密碼登錄](Chapter1/提交短信&支付密碼登錄.md)
使用typora打開以后，效果圖如下：
5、大功告成，gitbook可以實時刷新，當你用編輯器修改內容以后，馬上就可以在瀏覽器中看到效果。如果需要新增頁面，就直接修改SUmmary.md，修改完成頁面以后，執行 gitbook init就會自動創建。然后再用 typora打開編輯就行了。
后記：還可以使用gitbook功能生成pdf文檔，但是需要提前安裝 sudo apt-get install calibre 包，如果不安裝執行命令會報 InstallRequiredError: "ebook-convert" is not installed. Install it from Calibre: https://calibre-ebook.com 錯我。
在書籍目錄下執行命令：gitbook pdf ，就可以生成pdf文檔啦