使用Ruby项目Slate 构建API文档服务，漂亮的API文档

    查看原文请到我的个人网站 兵哥的领悟

       最近工作需要，为兄弟部门提供若干服务接口，遂需要编写API文档，供兄弟部门使用，经同事推荐 使用 slate最为编写和运行在线文档的服务，使用之后，发现还不错,这里记录一下。

    上图来自官网，官网上说 slate 配置简单、干净、上手快等等好处，等不及要试试了。

首先第一步，需要安装Ruby，已经有安装过的朋友直接跳过这一步吧！

1）从官网下载源码或者安装包 http://www.ruby-lang.org/en/downloads/ 下载Source Code或者RubyInstaller  从 http://rubyinstaller.org/downloads/下载RubyInstaller

slate 上面说选择1.9.3或更新的版本。

2）安装Ruby，选择下一步，安装到合适的目录就行了，这里略掉了，安装完成后然后设置环境变量如下，运行ruby -v 显示版本号则安装完成了。

 

SET RUBY_HOME=D:/ruby  
SET PATH=%PATH%;%RUBY_HOME%/bin  
SET RUBYOPT=rubygems

 

第二步，安装完Ruby后，安装Bundler 服务，这个  使用以下命令

gem install bundler

如果出现问题就先安装 json 的依赖，如果有问题，可以联系我

第三步，安装好Ruby 和Bundler 之后，就去slate下载包，如果你本地安装了Github客户端可以直接clone下来，如果不是就去下载后解压到本地合适目录。打开cmd cd到刚才解压的slate目录里面，运行 bundle install 然后运行服务。记得一定要在slate目录下面。

bundle exec middleman server

运行后命令行客户端出现服务启动的信息，如下图。

在浏览器里面敲如 http://localhost:4567 即可出现需要的api文档。

 

如何编辑呢？打开slate\source\includes 下面 你会发现一个_errors.md 的文件，你猜对了，他就是用来写api的，你复制一个重命名为_user.md(任意名称，但要下划线开头）

然后在里面编辑如我的demo，然后在slate\source目录下的index.md 下面加入

includes: 

  - errors

加入后

includes:

  - errors

  - video

 

你可以把errors模块去掉，实现自定义一下是我的模版。

# 欢乐课堂接口

## 1.3	获取筛选数据

```Java
略
```


> 返回的JSON示例:

```json
{
  ["1": {
  	grade:{1:"一年级"……},
  	semester:[上册,下册],
  	publish:{1:"人民邮电出版社",2:"清华大学出版社"……}
  },
  "2": {
  	grade:{1:"一年级"……},
  	semester:[上册,下册],
  	publish:{1:"人民邮电出版社",2:"清华大学出版社"……}
  }],
  updateTime : 172394433
}
```

### HTTP 请求

`GET /queryFilterData`

### 请求参数

参数 | 必选 | 默认 | 字段类型 | 字段说明
--------- | ------- | ------- | -------- | ----------
无

### 返回字段说明

参数  | 字段类型 | 字段说明
--------- | ----------- | -----------
status | string | 状态，有success和fail
filterData | String | json格式的字符串
updateTime | long 	| 最后更新时间


## 1.6	获取视频列表

```Java
略

> 返回的JSON示例:

```json
[ 
  {
	  "videoId": "1",
	  "videoImgUrl" : "http://xxx.com/asd.png",
	  "videoKnowdge","全等三角形"
  },
  {
	  "videoId": "2",
	  "videoImgUrl" : "http://xxx.com/asd.png",
	  "videoKnowdge","全等三角形"
  },
]
```

根据科目、年级、出版社信息获取视频列表。每本教材的根节点中必须包含此教材最后更新的日期，以便小机端更新本地缓存。

### HTTP 请求

`GET /queryVideos`

### 请求参数

参数    | 必选 | 默认 | 字段类型 | 字段说明
--------- | ------- | ------- | -------- | ----------
uid | true | null | string | 用户账号
subjectId | true | 0 | Integer | 科目ID
sectionId | true | 0 | Integer | 学段ID
gradeId |true | 0 | Integer | 年级ID
publishId |true | 0 | Integer | 出版社ID

### 返回字段说明

参数  | 字段类型 | 字段说明
--------- | ----------- | -----------
videoId	| String |	视频编号
videoImgUrl | String |	视频封面链接
videoKnowdge | String | 视频知识点,可带多个知识点

效果如图，怎么写大家自己领悟吧