apipie-rails gem: best documentation tool

Apipie-rails is a DSL and Rails engine for documenting you RESTful API. Instead of traditional use of #comments, Apipie lets you "describe the code by code". This brings advantages like:

It uses ruby syntax
Reusable doc for other purposes (Best for validations)
Easier to extend and maintain

apipie-rails gem owner has documented it in very nice way with examples. Refer [Github Documentaion(github doc)][1]

Path to documentation:

The documentation is available right in your app (by default under "/apipie" path.)

Also you can provide your own path using initializers. For more information refer [here(config link)][2]

Apipie.configure do |config|
  config.api_base_url            = "/api"
  config.doc_base_url            = "/api/docs"
  # where is your API defined?
  config.api_controllers_matcher = "#{Rails.root}/app/controllers/api/v1/*.rb"
  config.default_version         = "v1"
end

Steps to follow:

The easiest way to get Apipie up and running with your app is:

In your gemfile:
```
gem 'apipie-rails'
```
```
bundle install
```
Then set up the basic configuration:
```
rails g apipie:install
```

Now you can start documenting your resources and actions:

api :GET, '/users/:id'
param :id, :name
def show
  # ...
end

Run your application and see the result at http://localhost:3000/apipie

Resource Description:

Refer [here(link)][3]

resource_description do
  short 'List, create, update and delete offers.'
  formats ['json']
  error 401, "Unauthorized"
  error 404, "Not Found"
  error 422, "Validation Error"
  error 500, "Internal Server Error"
end

Parameter Description:

Refer [here(link)][4]

  param :user, Hash, desc: "User info" do
    param :username, String, desc: "Username for login", required: true
    param :password, String, desc: "Password for login", required: true
  end
  def create
    #...
  end

Param Group:

Refer [here(link)][5]

  def_param_group :offer do
    param :offer, Hash, required: true do
      param :state_event, Offer.valid_events, desc: "event description", allow_nil: true
      param :parking, [true, false], desc: "Is provided?", allow_nil: true
      param :estimated_size, String, desc: "How big is the item?", required: true
    end
  end

  api :POST, '/v1/offers', "Create an offer"
  param_group :offer
  def create
    # ...
  end

Example Recording:

Refer [here(link)][6]

You can also use the tests/rspec to generate up-to-date examples for your api documentayion.

APIPIE_RECORD=examples rspec

The data is written into doc/apipie_examples.yml. By default, only the first example is shown for each action. You can customize this by setting show_in_doc attribute at each example.

describe "Create User" do
  it "should return user record", :show_in_doc do
    ....
  end
end

and in rspec helper:

# Apipie can record examples using "APIPIE_RECORD=examples rake"
  config.filter_run :show_in_doc => true if ENV['APIPIE_RECORD']

Data will be loaded in doc/apipie_examples.json as

{
  "users#show" : [
    {
      "verb" : "GET",
      "path" : "/api/v1/users/1431",
      "versions" : [
        "v1"
      ],
      "query" : "",
      "request_data" : null,
      "response_data" : {
        "permissions" : [
          {
            "id" : 510,
            "name" : "Reviewer"
          }
        ],
        "user" : {
          "id" : 1431,
          "first_name" : "Guillermo",
          "last_name" : "Kohler",
          "mobile" : "90865267",
          "permission_id" : 510
        }
      },
      "code" : "200",
      "show_in_doc" : 1,
      "recorded" : true
    }
  ]
}

Demo application: [Click Here(link)][7]

API documentation of our application: [Click Here(link)][8]
[1]: https://github.com/Apipie/apipie-rails
[2]: https://github.com/Apipie/apipie-rails#configuration-reference
[3]: https://github.com/Apipie/apipie-rails#resource-description
[4]: https://github.com/Apipie/apipie-rails#parameter-description
[5]: https://github.com/Apipie/apipie-rails#dry-with-param_group
[6]: https://github.com/Apipie/apipie-rails#examples-recording
[7]: https://github.com/Apipie/apipie-demo
[8]: http://api.goodcity.hk/api/docs