Toll free (US) : +1 (888) 838-3532 | NYC: +1 (646) 491-6866

Making API for a Rails application is simple for a Ruby on Rails developer. In any case, how different clients/customers will know whether the API is working fine or not without a customer side application. Is there any answer for this which I can report for API inside the Rails application, The answer is yes we have numerous instruments and methodologies however I would favor swagger UI.

In this article I am going to disclose how to make Rails API documentation using swagger UI.

I am going to use one sample posts application which serves API calls.

To Integrate swagger UI for Rails API I am using a gem called swagger-docs. Add this gem to your Gemfile in your application and do bundle install.

Swagger initializer file:-
After bundling the gem create an initializer in config/initializers(e.g. swagger.rb) and specify the following options:

Refer below url for the list of configarations

swagger_controller and swagger_API are helpers to provide swagger UI documentation.


param – Standard API parameter

To handle enums:-
Pass list of enum values.

Generating json files:-

rake swagger:docs (Errors are not displayed by default with this command)

To see all error messages use the command below:

Swagger UI integration

Please download swagger ui.

Before that please add below code to swagger.rb to
make a distinction between the APIs and API documentation paths.

Create apidocs directory under public and api directory under apidocs.

Copy downloaded swagger-ui to the public/apidocs/api and index.html to public/apidocs.

Edit index.html
Change swagger url in window.swaggerUi function to url: “/apidocs/api-docs.json”.
It should be pointed to api-docs.json file under public/apidocs.
Because, it will generate under that path as per the configation we defined in swagger.rb

Now we all are set. IF you are running the the server stop and restart the rails server. Go to browser and try to access “http://localhost:3000/apidocs/index”. You can click on available links(show/hide, List operations, Expand Operations and Raw) on each resource(posts etc):

swagger-doc-1 swagger-doc-2

Also read : Track Changes To Your Model’s Data with Paper Trail Gem

Also read  :  Multi-tenant Architecture with PostgreSQL Schemas

Want to learn more about our Rails development skills and past projects ? Get in touch with us now !

WhatsApp chat