如何使用gitbook來編寫Api文檔

本篇內(nèi)容主要講解“如何使用gitbook來編寫Api文檔”，感興趣的朋友不妨來看看。本文介紹的方法操作簡單快捷，實用性強。下面就讓小編來帶大家學(xué)習(xí)“如何使用gitbook來編寫Api文檔”吧!

Gitbook的使用

當你使用Gitbook的時候，新建一個項目的時候，會彈出下面選項，共四種類型的模板提供給你選擇，實際上他們沒什么區(qū)別，只是一個Markdown模板：

我們選擇了第一項，當然，初次嘗試的朋友，可以都選擇看一看不同的Markdown模板。

如圖所示， Gitbook Editor，實際上就是一個特殊的Markdown編輯器。我創(chuàng)建了一個test項目作為示例，你也可以自己創(chuàng)建一本新書，然后打開源目錄，會看到如下文件：

SUMMARY.md 這個文件就是書的目錄結(jié)構(gòu)。Gitbook Editor對中文支持不太好，有時候你用Editor創(chuàng)建了一個章節(jié)，用中文命名，但是當你點擊那個新建的章節(jié)的時候，會報錯，解決辦法就是用你自己的編輯器打開這個文件，直接編輯這個文件就好了。

具體Editor如何上手，就不詳細說了，相信你會用Markdown編輯器就會用Editor。

當你創(chuàng)建了一本書之后，可以通過「Book->Publish As...」功能來把你的書發(fā)布到Gitbook，但是前提是你必須要在Gitbook網(wǎng)站上面也相應(yīng)創(chuàng)建好這本書。

你也可以通過使用Gitbook的幫助，使用Git來創(chuàng)建并上傳你的書：

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 line

git remote add gitbook https://push.gitbook.io/blackanger/test.git
git push -u gitbook master

你也可以在本地使用Editor的Preview Website功能，在本地_books目錄中生成靜態(tài)網(wǎng)頁，也就是書的Web版本。 早先的Gitbook Editor版本可以直接在本地生成epub、pdf、mobi格式的文件，但是最新版本把這些功能去掉了。

使用Gitbook寫你自己的Api文檔

Gitbook寫自己的書很方便，本人前段時間也發(fā)布了一本免費書籍《Chef之道》。其實你用Gitbook不只是可以寫書，也可以來寫Api文檔，我一直用Gitbook寫Api文檔，我總結(jié)了幾個優(yōu)點：

• Gitbook可以免費創(chuàng)建私有庫，保密性比較高。

• 類似于Github，有版本控制。就是一個電子書版的Github。

• Gitbook Editor是一個很好用的Markdown編輯器，有很多貼心的快捷鍵讓你發(fā)掘，比如cmd+shift+d，如果你用習(xí)慣Atom、Sublime、Textmate之類的編輯器，會很喜歡這些特性。當然此類快捷鍵也不是很多，但是相信以后Editor功能會更加豐富，因為我剛才說的這個特性應(yīng)該也是新加的。起碼比Logdown這個Markdown編輯器好用多了。

• 一次編寫，多處使用。接下來我們重點說這個，也就是我今天重點要說的。

一次編寫，多處使用。

現(xiàn)在是移動互聯(lián)網(wǎng)時代，很多App已經(jīng)開發(fā)在維護，還有很多很多的App待開發(fā)，而且HTML5、js mvc框架的發(fā)展，有很多人都在維護Api接口。那么寫一個可維護、可讀性高、帶版本控制、可隨心所欲分發(fā)的接口文檔是多么重要。

可讀性/ 可維護 / 版本控制

Gitbook是用Markdown寫的，還支持語法高亮等，用它寫出來的文檔，那看起來是相當愉悅的，看下圖示例。

Gitbook正是天生帶版本控制，你可以選擇任意一個你發(fā)布過的版本。

可隨心所欲分發(fā)

1. 文檔寫好以后，你可以把Gitbook源目錄下面的所有文件都復(fù)制到你項目下(app_root/docs/api/gitbook_api_dir)。這樣，你的項目就多了一份漂亮的文檔，開發(fā)人員還可以在本地打開Web Preview生成在_book目錄下的靜態(tài)網(wǎng)頁愉悅的看你的Api接口文檔。 如果覺得復(fù)制太土了，你可以直接把Gitbook Editor的Api文檔目錄創(chuàng)建在項目中。

2. 后臺接口項目、Android App項目、iOS App項目都可以分發(fā)一份，大家可以使用Gitbook Editor來協(xié)同管理接口。

3. 上傳到Github，也可以在線修改閱讀你的文檔，因為Github也支持Markdown。

是不是非常方便？

到此，相信大家對“如何使用gitbook來編寫Api文檔”有了更深的了解，不妨來實際操作一番吧！這里是億速云網(wǎng)站，更多相關(guān)內(nèi)容可以進入相關(guān)頻道進行查詢，關(guān)注我們，繼續(xù)學(xué)習(xí)！