使用Gitbook来编写你的Api文档

Published on:

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正是天生带版本控制,你可以选择任意一个你发布过的版本。

可随心所欲分发

  1. 文档写好以后,你可以把Gitbook源目录下面的所有文件都复制到你项目下(app_root/docs/api/gitbook_api_dir)。这样,你的项目就多了一份漂亮的文档,开发人员还可以在本地打开Web Preview生成在_book目录下的静态网页愉悦的看你的Api接口文档。 如果觉得复制太土了,你可以直接把Gitbook Editor的Api文档目录创建在项目中。

  2. 后台接口项目、Android App项目、iOS App项目都可以分发一份,大家可以使用Gitbook Editor来协同管理接口。

  3. 上传到Github,也可以在线修改阅读你的文档,因为Github也支持Markdown。

是不是非常方便?


Update: 就在我写完本文之后,我就发现gitbook增加了付费计划, 免费的私有项目只允许创建一个。

Comments

comments powered by Disqus