Skip to content

Latest commit

 

History

History
147 lines (96 loc) · 3.72 KB

README.rdoc

File metadata and controls

147 lines (96 loc) · 3.72 KB
Raw

Rapidoc ↑

REST API documentation generator for rails projects ( 0.07 version ).

This gem let you generate API documentation of your rails project in html format. It uses routes information, rapidoc comments and json examples for generate static html files. Documentation templates are generated using handlebars and bootstrap.

This is how the web interface look like: example

Rapidoc is based in restapi_doc gem.

Installation ↑

Add this line to your application’s Gemfile:

gem 'rapidoc'

Then execute:

$ bundle

And finally, run:

rake rapidoc:install

Usage ↑

For generate documentation run:

rake rapidoc:generate

For clean all generate files run:

rake rapidoc:clean

Introducction ↑

If you generate documentation without do anithing, you can get all resources list in a index.html file.

For get resources documentation you need add a resource block to resource controller:

# =begin resource
# =end

For get action documentation you need add an action block to resource controller:

# =begin action
# =end

Documentation blocks use yaml format.

Documentation example ↑

Resource documentation:

# users_controller.rb

# =begin resource
# description: Represents an user in the system.
# =end

Action documentation:

# =begin action
# method: GET
# action: index
# requires_authentication: no
# response_formats: json
# description: Return all users of the system.
#
# http_responses:
#   - 200
#   - 401
#   - 403
#
# params:
#   - name: page
#     description: number of page in pagination
#     required: false
#     type: Integer
#
#   - name: limit
#     description: number of elements by page in pagination
#
#   - name: name
#     description: name filter
# =end
def index
  ...
end

Configuration ↑

You can configure rapidoc in “/config/rapidoc/rapidoc.yml“ file:

project_name: "Project Name"
company: "My company"
year: 2013
doc_route: "doc"
examples_route: "examples"

The first three parameters are used for show information about project in the documentation.

The doc_route parameter let you specify where rapidoc will generate the documentation:

path_project/doc

The examples_route parameter let you specify where rapidoc will search for requests/responeses examples files:

path_project/examples

For more details and options please visit the Wiki.

Other Options ↑

  • You can use .yml files for write documentation blocks ( configuration ).

  • Rapidoc let you define json files with requests/responses examples ( examples )

  • Rapidoc let you use default errors ( errors )

  • Rapidoc has a lot of parameters for document actions of resource ( actions )

  • When you are in an action page, you can click the resource name and go back to the resources page with resource selected.

  • If there is an error in your documentation, rapidoc show you an error message with the file name that contains the error and block lines.

  • Trace mode ( configuration ).

  • Simple and intuitive navigation.

Contributors ↑

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