= Rapidoc

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

This gem let you generate API documentation of your rails project in html format.
It use routes information, _rapidoc_ _comments_ and json examples for generate
static html files.

This is how the web interface look like:

* Resources: example[http://www.v2imagen.com/RDv]
* Action-home: example[http://es.zimagez.com/zimage/capturadepantalla-170213-195254.php]

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

== Installation

Add this line to your application's Gemfile:

    gem 'rapidoc', :git => 'https://github.com/drinor/rapidoc.git'

And then execute:

    $ bundle

== Usage

For generate documentation run:

    rake rapidoc:generate

For clean all generate files run:

    rake rapidoc:clean

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

The *doc_route* parameter let you specify where _rapidoc_ will generate all the
documentation:

  path_project/name

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

  path_project/name

For more details please visit the Wiki[https://github.com/drinor/rapidoc/wiki].

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

== Requests/Responses examples

Rapidoc let you define *json* files with requests/responses examples. You only need to add
your files to *examples_route* and _rapidoc_ load it automatically in an action tab.

Files should have the next name format:

  <resource>_<action>_<type>.json

Parameters:

* *resource*: name of resource (plural)
* *action*: controller action (index, create, show...)
* *type*: request / response

Name example:

  users_create_request.json

File example:

  {
    "usuario": {
      "name": "Paul",
      "age": 23,
      "height": 1.7,
      "favoriteBands": ["Band ABC", "Band XYZ"]
    }
  }

== Documentation examples

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

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