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

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

28 Dec 2017
0 Comments
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 systems 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 specifications that can be used by a 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 documents 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

The above command examines your controllers to determine which controllers should be documented for swagger-UI.

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




Leave a comment: