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 [CODES_PATH=app/controllers/api] [OUT_FORMAT=simple_html|detailed_html]

代码注释格式:


  # About: 文件说明
  # 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中查找出来

Level

默认level显示所有
输出时只会显示指定level的api
所有的level为: read search update create delete
使用： rake doc:api LEVEL=read,search

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request