使用Gitbook來編寫你的Api文檔
Gitbook是一個很優秀的社區，上面有很多優秀的作者自出版自己的著作，就好像Leanpub，可能很多人喜歡Leanpub，但是我還是喜歡Gitbook，這種類似於Github的原創社區。同時Gitbook還提供一個開源的配套的工具。也許看到此文章的很多人很早就知道Gitbook，但是也許你沒有使用過，現在Gitbook已經比較成熟了，功能也比較完善。下面我們首先來介紹下Gitbook的使用。
Gitbook的使用
當你使用Gitbook的時候，新建一個項目的時候，會彈出下面選項，共四種類型的模板提供給你選擇，實際上他們沒什么區別，只是一個Markdown模板：
我們選擇了第一項，當然，初次嘗試的朋友，可以都選擇看一看不同的Markdown模板。
如圖所示， Gitbook Editor，實際上就是一個特殊的Markdown編輯器。我創建了一個test項目作為示例，你也可以自己創建一本新書，然后打開源目錄，會看到如下文件：
- _book 文件夾
- SUMMARY.md
- README.md
SUMMARY.md 這個文件就是書的目錄結構。Gitbook Editor對中文支持不太好，有時候你用Editor創建了一個章節，用中文命名，但是當你點擊那個新建的章節的時候，會報錯，解決辦法就是用你自己的編輯器打開這個文件，直接編輯這個文件就好了。
具體Editor如何上手，就不詳細說了，相信你會用Markdown編輯器就會用Editor。
當你創建了一本書之后，可以通過「Book->Publish As...」功能來把你的書發布到Gitbook，但是前提是你必須要在Gitbook網站上面也相應創建好這本書。
你也可以通過使用Gitbook的幫助，使用Git來創建並上傳你的書：
touch README.md SUMMARY.md
git init
git add README.md SUMMARY.md
git commit -m "first commit"
git remote add gitbook https://push.gitbook.io/blackanger/test.git
git push -u gitbook master
…or push an existing repository from the command linegit remote add gitbook https://push.gitbook.io/blackanger/test.git
git push -u gitbook master
你也可以在本地使用Editor的Preview Website功能，在本地_books目錄中生成靜態網頁，也就是書的Web版本。 早先的Gitbook Editor版本可以直接在本地生成epub、pdf、mobi格式的文件，但是最新版本把這些功能去掉了。
使用Gitbook寫你自己的Api文檔
Gitbook寫自己的書很方便，本人前段時間也發布了一本免費書籍《Chef之道》。其實你用Gitbook不只是可以寫書，也可以來寫Api文檔，我一直用Gitbook寫Api文檔，我總結了幾個優點：
- Gitbook可以免費創建私有庫，保密性比較高。
- 類似於Github，有版本控制。就是一個電子書版的Github。
- Gitbook Editor是一個很好用的Markdown編輯器，有很多貼心的快捷鍵讓你發掘，比如cmd+shift+d，如果你用習慣Atom、Sublime、Textmate之類的編輯器，會很喜歡這些特性。當然此類快捷鍵也不是很多，但是相信以后Editor功能會更加豐富，因為我剛才說的這個特性應該也是新加的。起碼比Logdown這個Markdown編輯器好用多了。
- 一次編寫，多處使用。接下來我們重點說這個，也就是我今天重點要說的。
一次編寫，多處使用。
現在是移動互聯網時代，很多App已經開發在維護，還有很多很多的App待開發，而且HTML5、js mvc框架的發展，有很多人都在維護Api接口。那么寫一個可維護、可讀性高、帶版本控制、可隨心所欲分發的接口文檔是多么重要。
可讀性/ 可維護 / 版本控制
Gitbook是用Markdown寫的，還支持語法高亮等，用它寫出來的文檔，那看起來是相當愉悅的。
Gitbook正是天生帶版本控制，你可以選擇任意一個你發布過的版本。
可隨心所欲分發
-
文檔寫好以后，你可以把Gitbook源目錄下面的所有文件都復制到你項目下(app_root/docs/api/gitbook_api_dir)。這樣，你的項目就多了一份漂亮的文檔，開發人員還可以在本地打開Web Preview生成在_book目錄下的靜態網頁愉悅的看你的Api接口文檔。 如果覺得復制太土了，你可以直接把Gitbook Editor的Api文檔目錄創建在項目中。
-
后台接口項目、Android App項目、iOS App項目都可以分發一份，大家可以使用Gitbook Editor來協同管理接口。
-
上傳到Github，也可以在線修改閱讀你的文檔，因為Github也支持Markdown。
是不是非常方便？
Update： 就在我寫完本文之后，我就發現gitbook增加了付費計划， 免費的私有項目只允許創建一個。