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.