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

28 Dec 2017
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:

"1.0" => {
:api_extension_type =>:json,
# path for .json files 
:api_file_path =>"public",
:base_path =>"",
: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

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


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.

Leave a comment:

Recent Blogs
Contact-Us Contact-Us
Newsletter Newsletter