Passerelle

Passerelle is a convention-over-configuration OpenAPI schema builder for Rails. It's a simple engine you mount in your routes that automatically generates OpenAPI 3.0 schemas from your Rails models.

⚠️ Work in Progress: Passerelle is under development. Nothing works yet.

Philosophy

  • Convention first: Your database and ActiveRecord layer dictate the schema defaults. Easy to keep aligned with changes.
  • Write as little as possible, as much as necessary: Layer in types and customizations only where needed. Convention handles the rest.
  • Verifiable: Generate schema dumps, test against them, commit and track changes.

Installation

Add this line to your application's Gemfile:

gem 'passerelle'

And then execute:

bundle install

Quick Start

  1. Create a schema class:
# app/api/api_schema.rb
class ApiSchema < Passerelle::Schema
  # That's it! Convention generates CRUD endpoints for all models
end
  1. Generate and view your OpenAPI spec:
ApiSchema.new.to_json  # => Full OpenAPI 3.0 specification

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports, feature requests, and ideas are welcome on GitHub at https://github.com/manufaktor/passerelle.

Note: This project is not currently accepting code contributions (pull requests), but feedback and suggestions are always appreciated.