= Rapidoc

REST API documentation generator for rails projects ( 0.06 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[http://drinor.github.io/rapidoc/index.html]

Rapidoc is based in restapi_doc[https://github.com/Alayho/restapi_doc] gem.

== Installation

Add this line to your application's Gemfile:

    gem 'rapidoc'

And then execute:

    $ bundle

== 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[https://github.com/drinor/rapidoc/wiki].

== Other Options

* You can use .yml files for write documentation blocks ( configuration[https://github.com/drinor/rapidoc/wiki/Configuration] ).

* Rapidoc let you define *json* files with requests/responses examples ( examples[https://github.com/drinor/rapidoc/wiki/Request---Response-Examples] )

* Rapidoc let you use default errors ( errors[https://github.com/drinor/rapidoc/wiki/Params-Errors] )

* Rapidoc has a lot of parameters for document actions of resource ( actions[https://github.com/drinor/rapidoc/wiki/Action-Documentation] )

* 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[https://github.com/drinor/rapidoc/wiki/Configuration] ).

* Simple and intuitive navigation.

== 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