How to generate Rails REST API documentation similar to swagger?

Unlike any documentation, the REST API documentation is something very important. When we write REST API, it is useful to add API documentation for the API consumers. Without proper documentation, it becomes extremely difficult to reveal the required parameters and hidden usage.

In most languages, the API documentation can be generated. In Java Sprint boot we can add swagger documentation very easily. Similarly, in rails, we have many options for adding REST API documentation.

In this post, we are going to use 'apipie-rails' to generate REST API documentation.

Add the gem in Gemfile

gem 'apipie-rails'

If we integration the above gem using bundle install then we are ready to use inside the controller. Following is the code segment of generating generate REST API documentation:

  error :code => 401, :desc => "Unauthorized"
  error :code => 404, :desc => "Not Found", :meta => {:anything => "Not found"}
  api :GET, "/", "Single JSON content based on content type"
  header 'X-Auth-Token', 'Authorized token',  :required => true
  param :id, :number, desc: 'id of the requested content', :required => true
  param :type, String, desc: 'Type of the content (article, image, author)', :required => false
  returns :code => 200, :desc => "Success" do
     property :@jsondata, Hash, :desc => "An object"
  end
  formats ['json']
  def api

Reference:
How to auto-generate Rails REST API documentation for controllers?

Github:
https://github.com/Apipie/apipie-rails