文档
将slate集成到项目中
$ mkdir app/docs
集成slate
$ cd app/docs
$ git clone git@github.com:tripit/slate.git
$ rm -rf slate/.git
$ cd slate
$bundle install
配置构建文件app/docs/slate/config.rb
+ set :build_dir, '../../../public/docs/'
现在开始编写获取用户信息这个API的文档
app/docs/slate/source/index.md
---
title: API Reference
language_tabs:
- ruby
toc_footers:
- <a href='http://github.com/tripit/slate'>Documentation Powered by Slate</a>
includes:
- errors
search: true
---
# 介绍
API文档
#获取用户信息
## V1
## HTTP请求
`GET http://my-site/api/v1/users/<id>`
## 请求参数
参数名 | 是否必须 | 描述
--------|------------| -------
id | 是 | 用户id
##响应
\```json
{
"user":
{
"id":1,
"email":"test-user-00@email.com",
"name": "test-user-00",
"activated": "2015-05-02T07:47:14.697Z",
"admin":false,
"created_at":"2015-05-02T07:47:14.708Z",
"updated_at":"2015-05-02T07:47:14.708Z"
}
}
\``````
##给API文档加访问权限
**配置路由:**
**```routes.rb```**
- get '/docs/index', to: 'docs#index'
**建立相关控制器**
$ rails g controller docs
**修改```app/controllers/docs_controller.rb```**
class DocsController < ApplicationController
USER_NAME, PASSWORD = 'doc_reader', '123123'
before_filter :basic_authenticate
layout false
def index
end
private
def basic_authenticate
authenticate_or_request_with_http_basic do |user_name, password|
user_name == USER_NAME && password == PASSWORD
end
end
end
**同时我们需要把```public/docs/index.html```文件转移到```app/views/docs/```目录下面**。
**我们可以写一个脚本```docs_build.sh```，注意将这个脚本放在项目的根目录下。**
!/bin/bash
app_dir=pwd
cd $app_dir/app/docs/slate
bundle exec middleman build --clean
cd $app_dir
mv $app_dir/public/docs/index.html $app_dir/app/views/docs
**重建build文档**
$ ./docs_build.sh
