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 integration: Works with grape-entity and dry-struct
• Automatic type inference: Derives OpenAPI types from Grape parameter definitions
• Flexible output: Mount as an endpoint or generate programmatically

Compatibility

grape-oas	grape	grape-entity	dry-struct	Ruby
0.1.x	>= 3.0	>= 0.7	>= 1.0	>= 3.2

Installation

gem 'grape-oas'

For entity support:

gem 'grape-entity'  # For grape-entity support
gem 'dry-struct'    # For dry-struct contract support

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

Manual Generation

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

Rake Tasks

# In Rakefile
require 'grape_oas/tasks'

rake grape_oas:generate[MyAPI,oas31,spec/openapi.json]

Documentation

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 }
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 test

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.