Simple way to document API in Ruby on Rails using swagger document

After creating REST API, it’s important that API should be documented, so the others can use the documentation and understand the requirement and implementation of API.

Swagger documentation provides the interface to REST APIs which allows people and system to understand the API without access to source code.

Use ‘swagger-docs’ gem to document the API.

This will generate swagger-ui json files for rails apps with APIs specification that can be used by person to know about the APIs.

To start create swagger_docs.rb file in config/initializers and define your APIs as below:

Swagger::Docs::Config.register_apis({ "1.0" => { :api_extension_type =>:json, # path for .json files :api_file_path =>"public", :base_path =>"http://api.somedomain.com", :clean_directory =>false, :attributes => { :info => { "title" =>"Swagger Sample App", } } } })

Swagger document contain the json controller which has the API swagger_controller directives.

For example ItemsController has the API specification

classItemsController defshow render:json => {result:"Success"}, :status =>200 end end

Run rake task to generate docs

Rake swagger: docs

Above command examines your controllers to determine which controllers should be documented for swagger-ui.

Generate the api-docs.json output in public folder which contains the API specification for the items_swagger controller.

Written by,

Nandini Raut,

Cryptex Technologies

Source: http://www.cryptextechnologies.com/blogs/simple-way-to-document-api-in-ruby-on-rails-using-swagger-document