Effortless API Documentation with Grape, Grape Swagger, and rswag-ui

Effortless API Documentation with Grape, Grape Swagger, and rswag-ui

Documenting APIs can be a tedious chore, but it's essential for developers to understand and use your API effectively. Luckily, the Ruby ecosystem provides powerful tools to streamline this process. In this post, we'll explore how to combine Grape, Grape Swagger, and rswag-ui to effortlessly generate beautiful, interactive API documentation.

Grape: A Powerful Foundation

Grape is a lightweight framework for building REST-like APIs in Ruby. It simplifies API development with a clean, DSL-like syntax for defining endpoints, handling parameters, and formatting responses.

# app/api/v1/books.rb module V1 class Books Grape::API format :json resource :book do desc 'Get a list of books' get do Book.all end desc 'Create a new book' params do requires :name, type: String, desc: 'Book name' requires :author_name, type: String, desc: 'Author name' end post do Book.create!(declared(params)) end end end end 

Grape Swagger automatically generates Swagger documentation from your Grape API definitions. Simply include it in your Gemfile

# Gemfile gem 'grape-swagger' 

Now, to enhance your API documentation further, add the following configuration to your base API class:

# app/api/v1/base.rb module V1 class Base < Grape::API mount V1::Books add_swagger_documentation( api_version: 'v1', mount_path: '/api-docs', info: { title: 'API title', description: 'API description' } ) end end 

This configuration sets up Swagger documentation for your Grape API:

• api_version: Specifies the version of your API, which is 'v1' in this case.
• mount_path: Defines the URL path where the Swagger UI will be mounted (/api-docs). It will return json response for swagger document on api/v1/api-docs.
• info: Provides basic information about your API, including the title and a brief description.

By including this configuration in your Grape API, you enable Swagger to automatically generate documentation based on your API definitions. This documentation can then be accessed through the Swagger UI(rswag-ui).

rswag-ui: An Interactive UI for Swagger

rswag-ui takes your API documentation to the next level by providing an interactive environment where developers can explore and experiment with your API. It's like a playground for your API, allowing developers to get hands-on experience without writing any code.

This UI documentation empowers developers to:

• Explore endpoints and parameters: Easily browse, view descriptions, and understand requirements.
• Make test requests: Execute requests directly within the documentation, inputting data and inspecting responses.
• View response codes and schemas: Understand response structures and handle different scenarios effectively.

rswag-ui transforms your API documentation into a dynamic tool for understanding and experimentation.

To integrate rswag-ui, add these to your Gemfile, routes.rb and initializers/swagger.rb:

# Gemfile gem 'rswag-ui' # config/routes.rb mount Rswag::Ui::Engine => '/api-docs' # config/initializers/swagger.rb Rswag::Ui.configure do |c| # This line instructs rswag-ui to fetch the Swagger JSON definition  # from '/api/v1/api-docs' and display it in the interactive UI. c.swagger_endpoint '/api/v1/api-docs', 'API V1' # c.swagger_endpoint '/api/v2/api-docs', 'API V2' Example for multiple API versions end 

This will mount rswag-ui at /api-docs. Now you can access a beautiful, interactive documentation page for your API.

Here is how it looks (http://localhost:3000/api-docs/index.html):

Conclusion

By leveraging Grape, Grape Swagger, and rswag-ui, you can significantly reduce the effort required to document your Rails APIs. This powerful combination allows you to focus on building your API while ensuring your documentation is always up-to-date and easy to understand.