RailsApiDoc
rails api document generation
Installation
Add this line to your application's Gemfile:
gem 'api_doc_generation'
And then execute:
$ bundle
Or install it yourself as:
$ gem install api_doc_generation
Usage
rake doc:api [opts=xxx]
参数说明:
- CODES_PATH 指定生成代码路径,默认为app/controllers/api
- OUT_FORMAT simple_html 或者 detailed_html, 默认使用detailed_html 模板
- SHOW_BASE 是否为*BaseController结尾的controller生成文档,默认为false
代码注释格式: d
# 文件说明 # About: xxxx # Host: 定义api host # Other: ... class Api::UsersController < class Api::BaseController # 取得所有用户 # # Params: # page: [Integer] 页数 # perpage: [Integer] 每页数量 # Return: # count: [Integer] 数据总条数 # items: [Array] 当前页数据的数组 # Level: read def list # ... end
# (api说明)取得一个用户的信息
#
# Params:
# user_id: [String] 用户的id
# Return:
# name: [String] xxx
# Error:
# info: [String] 自己定义的错误信息
# other: [String] 如果不设置的,将生成默认的
def show
# ...
end
# 自定义路由
#
# Path: /path/to/api
# Method: POST
# Params:
# user_id: [String] 用户的id
# Return:
# name: [String] xxx
# Other: 自定义的信息
# Other2: 更多的自定义信息..
def update
# ...
end
end
上面已经给出了api说明,参数,返回,错误信息,而api地址和请求方法将会自动从Rails中查找出来
__总的来说,注释格式有三种__
1. 只一层
层级1: 说明
2. 两层
层级1:
层级2: 说明
层级2: 说明
3. 超过两层
层级1:
层级2: 说明
层级3
更多的层级,这些层级只会显示在层级2中,等于就是层级2的说明
字段2: 说明
上面的格式可以任意组合,要注意的是,解析时层级是按 (空格 / 2)来计算的
## Level
* 默认level显示所有
* 输出时只会显示指定level的api
* 所有的level为:
```read search update create delete```
* 使用:
``` rake doc:api LEVEL=read,search```
## 注意
为加强文档规范化,以下情况的controller将不再生成显示出来:
1. 当前Controller没有文件说明
2. 当前controller的actions数量为0
3. 当前action没有Return说明
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request