使用 slate 编写完美的 HTTP API 文档

前言

slate 是一个让你使用 markdown 写 HTTP API 文档的工具,还能生成漂亮的静态页面。支持 markdown 意味着可以极大程度的提高编写效率,纯文本意味着可以使用代码管理工具 git 管理,review,自动编译和发布。下面将详细介绍如何使用这个工具。

准备工作

slate 需要 ruby2 运行环境,所以先装 ruby,gtt 使用的是 ubuntu 14.04 发行版,其他发行版可能会有些区别。

$ sudo apt-add-repository ppa:brightbox/ruby-ng
$ sudo apt-get install ruby2.0 ruby2.0-dev nodejs -y

# 将默认的 ruby 和 gem 改成 2.0

$ sudo rm /usr/bin/ruby
$ sudo ln -s /usr/bin/ruby2.0 /usr/bin/ruby

$ sudo rm /usr/bin/gem
$ sudo ln -s /usr/bin/gem2.0 /usr/bin/gem
$ ruby --version
ruby 2.0.0p384 (2014-01-12) [x86_64-linux-gnu]

安装完成后配置写 ruby 的镜像,因为 ruby 的官方源在国内访问特别特别特别的慢,幸好 taobao 提供了 ruby 相关的镜像,下面两条配置将 gem 的源都指向 ruby.taobao.org

gem sources --add https://ruby.taobao.org/ --remove https://rubygems.org/

确保 gemrc 配置文件里没有 rubygems.org,下面是设置正确的配置文件内容。

---
:backtrace: false
:benchmark: false
:bulk_threshold: 1000
:sources:
- https://ruby.taobao.org/
:update_sources: true
:verbose: true

安装 bundle

$ sudo gem install bundler
Fetching: bundler-1.12.5.gem (100%)
Successfully installed bundler-1.12.5
1 gem installed
Installing ri documentation for bundler-1.12.5...
Installing RDoc documentation for bundler-1.12.5...

也配置 bundle 使用 taobao 的源

bundle config mirror.https://rubygems.org https://ruby.taobao.org

安装 slate

git clone https://github.com/lord/slate

如果嫌慢,可以使用

git clone https://coding.net/gtt116/slate

装一些依赖包,slate 依赖的 gem 包需要这些依赖

sudo apt-get install -y zlib1g-dev  libxslt-dev libxml2-dev  # nokogiri 需要

正式安装

$ cd slate
$ bundle install                   
Fetching gem metadata from https://ruby.taobao.org/.............
Fetching version metadata from https://ruby.taobao.org/..
Rubygems 1.8.23 is not threadsafe, so your gems will be installed one at a time. Upgrade to Rubygems 2.1.0 or higher to enable parallel gem installation.
Installing rake 10.4.2
Installing i18n 0.7.0
Installing json 1.8.3 with native extensions

.......省略很多...........

Installing hamster 2.0.0
Installing rb-inotify 0.9.5
Installing haml 4.0.7
Installing middleman-cli 4.0.0
Installing activesupport 4.2.5.1
........
Bundle complete! 7 Gemfile dependencies, 51 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.

如果报错的话,就按照提示把该装的包装上,一般是依赖的 deb 包没有。

开启调试模式

$ bundle exec middleman server
== The Middleman is loading
== View your site at "http://localhost:4567", "http://127.0.0.1:4567"
== Inspect your site configuration at "http://localhost:4567/__middleman", "http://127.0.0.1:4567/__middleman"

打开本地的 http://localhost:4567 即可看到效果:
slate

这种 middleman 模式适合编写文档时使用,因为每次 markdown 源码有变动会实时生效,效率很高。
如果要文档已经成型,需要发布到网站上,可以通过下面的命令生成静态 html 文件:

$ bundle exec middleman build --clean

在 build 目录中就是生成的静态文件。

编写

源代码位于 slate/source/index.html.md,前面定义了文件的标题,支持的源代码类型,目录页脚等,是否支持搜索等配置。可以任意修改,下面就是正常的 markdown 语法。

为了方便管理,可以将 API 分成很多小模块,放到 slate/source/includes/ 目录下,然后再 index.html.md 中引用这个文件即可。比如:

index.html.md 中这么引用

includes:
   - errors 

那么 slate 将去 slate/source/includes/ 目录下寻找_errors.md 文件,请注意 文件名一定要有 _ 开头,但是 include 中不包含 _ 以及后缀名 md

更多 slate 可以看官方的 wiki

最后

还有多少公司在用 word 写 HTTP 文档,在邮件里传来传去。还在一遍一遍和新员工说:“你的版本太旧了,我发个新的文档给你”。文档管理也是一门学问,一个好公司在知识整理上肯定会下大功夫。

发表评论

电子邮件地址不会被公开。 必填项已用*标注