Grape::OAS

OpenAPI Specification (OAS) documentation generator for Grape APIs. Supports OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications.

Table of Contents

• Why Grape::OAS?
• Features
• Compatibility
• Installation
• Quick Start
  • Mount Documentation Endpoint
  • Manual Generation
  • Rake Tasks
• Documentation
• Basic Usage
  • Documenting Endpoints
  • Response Documentation
  • Entity Definition
• Extensibility
  • Custom Introspectors
  • Custom Exporters
• Related Projects
• Development
• Contributing
• License

Why Grape::OAS?

Grape::OAS is built around a DTO (Data Transfer Object) architecture that separates collecting API metadata from generating schemas. This clean separation makes the codebase easier to reason about and enables support for multiple output formats (OAS 2.0, 3.0, 3.1) from the same API definition.

Features

• Multi-version support: Generate OAS 2.0, 3.0, or 3.1 from the same API
• Entity and contract integration: Works with grape-entity, dry-validation, and dry-schema
• Automatic type inference: Derives OpenAPI types from Grape parameter definitions
• Flexible output: Mount as an endpoint or generate programmatically

Compatibility

grape-oas	grape	Ruby
1.5.x	>= 3.0	>= 3.2

Entity and contract integrations are optional; install the gems your API uses.

Installation

gem 'grape-oas'

For entity or contract support, add the relevant gems:

gem 'grape-entity'    # Grape::Entity response schemas
gem 'dry-validation'  # Dry::Validation::Contract request schemas
gem 'dry-schema'      # Standalone Dry::Schema request schemas

Quick Start

Mount Documentation Endpoint

class API < Grape::API
  format :json

  add_oas_documentation(
    info: {
      title: 'My API',
      version: '1.0.0'
    }
  )

  resource :users do
    desc 'List users', entity: Entity::User
    get { User.all }
  end
end

Documentation available at:

• /swagger_doc - OpenAPI 3.0 (default)
• /swagger_doc?oas=2 - OpenAPI 2.0
• /swagger_doc?oas=3.1 - OpenAPI 3.1

Documentation routes are accessible over HTTP but excluded from the generated specification by default. Set hide_documentation_path: false to include them. To disable the endpoints, omit or conditionally call add_oas_documentation.

Manual Generation

# Generate OpenAPI 3.0 spec
spec = GrapeOAS.generate(app: API, schema_type: :oas3)
puts JSON.pretty_generate(spec)

Rake Tasks

Load your API before registering the tasks:

# In Rakefile
require 'grape_oas'
require 'grape_oas/rake/oas_tasks'
require_relative 'app/api' # Defines MyAPI; adjust to your application's path

GrapeOAS::Rake::OasTasks.new(MyAPI)

mkdir -p spec
bundle exec rake oas:generate version=oas31 output=spec/openapi.json

Documentation

Upgrading an existing application? Read UPGRADING.md.

Document	Description
Configuration	All configuration options
Usage Guide	Detailed usage examples
Architecture	System architecture overview
Introspectors	Custom introspector development
Exporters	Custom exporter development
API Model	Internal API model reference

Basic Usage

Documenting Endpoints

desc 'Get a user by ID',
  detail: 'Returns detailed user information',
  tags: ['users']

params do
  requires :id, type: Integer, desc: 'User ID'
end

get ':id' do
  User.find(params[:id])
end

Response Documentation

desc 'Get user' do
  success Entity::User
  failure [[404, 'Not Found'], [500, 'Server Error']]
end

Entity Definition

class Entity::User < Grape::Entity
  expose :id, documentation: { type: Integer }
  expose :name, documentation: { type: String }
  expose :posts, using: Entity::Post, documentation: { is_array: true }

  # Block-based nesting produces an inline object schema
  expose :meta do
    expose :role, documentation: { type: String, values: %w[admin user guest] }
    expose :verified, documentation: { type: 'Boolean' }
  end
end

Extensibility

Custom Introspectors

class MyModelIntrospector
  extend GrapeOAS::Introspectors::Base

  def self.handles?(subject)
    subject.is_a?(Class) && subject < MyBaseModel
  end

  def self.build_schema(subject, stack: [], registry: {})
    GrapeOAS::ApiModel::Schema.new(type: "object", canonical_name: subject.name)
  end
end

GrapeOAS.introspectors.register(MyModelIntrospector)

Custom Exporters

GrapeOAS.exporters.register(MyCustomExporter, as: :custom)
schema = GrapeOAS.generate(app: API, schema_type: :custom)

Related Projects

Project	Description
grape	REST-like API framework for Ruby
grape-entity	Entity exposure for Grape APIs
grape-swagger	OpenAPI documentation for Grape APIs
grape-swagger-entity	grape-swagger adapter for grape-entity
oas_grape	Another OpenAPI 3.1 generator for Grape

Development

git clone https://github.com/numbata/grape-oas.git
cd grape-oas
bin/setup
bundle exec rake

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/numbata/grape-oas. See CONTRIBUTING.md for guidelines.

License

MIT License. Copyright (c) Andrei Subbota.