使用Gitbook来编写你的Api文档

Published on: November 18, 2014

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 line

git 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增加了付费计划，免费的私有项目只允许创建一个。

转自：http://tao.logdown.com/posts/243192-use-gitbook-to-write-api-documentation

转载于:https://www.cnblogs.com/timchen5858/p/4859607.html