R2-OAS

Generate api document (OpenAPI) side only from Rails routing.

Provides a rake command to help generate, view, and edit OpenAPI documents.

bundle exec rake routes:oas:init    # r2-oas initialize
bundle exec rake routes:oas:docs    # generate oas_docs
bundle exec rake routes:oas:ui      # view at swagger ui
bundle exec rake routes:oas:editor  # edit at swagger editor
bundle exec rake routes:oas:monitor # monitor oas_docs and analyze
bundle exec rake routes:oas:build   # build oas_docs from src
bundle exec rake routes:oas:clean   # clean unused components
bundle exec rake routes:oas:analyze # analyze oas_docs and generae src
bundle exec rake routes:oas:deploy  # deploy oas_docs to deploy_docs

💎 Installation

Add this line to your application’s Gemfile:

group :development do
  gem 'r2-oas'
end

And then execute:

$ bundle

Or install it yourself as:

$ gem install r2-oas

🔦 Requirements

If you want to view with Swagger UI or edit with Swagger Editor, This gem needs the following:

If you do not have it download as below.

$ docker pull swaggerapi/swagger-editor:latest
$ docker pull swaggerapi/swagger-ui:latest
$ brew install chromedriver

🚀 Tutorial

After requiring a gem and Configure Rakefile in your rails project

R2OAS.load_tasks

$ bundle exec rake routes:oas:init
      create	oas_docs
      create	oas_docs/.paths
      create	oas_docs/plugins/helpers
      create	oas_docs/tasks/helpers
      create	oas_docs/plugins/.gitkeep
      create	oas_docs/plugins/helpers/.gitkeep
      create	oas_docs/tasks/.gitkeep
      create	oas_docs/tasks/helpers/.gitkeep
$ bundle exec rake routes:oas:docs
$ bundle exec rake routes:oas:editor

Generate docs

https://github.com/user-attachments/assets/0d094a92-dbcd-49f0-9ef0-e1809f0710a9

Edit docs

https://github.com/user-attachments/assets/e10a695c-1d18-4da6-8827-28cb3d0b9e3a

Usage

You can execute the following command in the root directory of rails.
The following are examples of typical command usage.

Full docs are available at https://yukihirop.github.io/r2-oas

Initialize

Initialize r2-oas.

$ bundle exec rake routes:oas:init
      create	oas_docs
      create	oas_docs/.paths
      create	oas_docs/plugins/helpers
      create	oas_docs/tasks/helpers
      create	oas_docs/plugins/.gitkeep
      create	oas_docs/plugins/helpers/.gitkeep
      create	oas_docs/tasks/.gitkeep
      create	oas_docs/tasks/helpers/.gitkeep

Generate

Generate docs.

$ bundle exec rake routes:oas:docs                                                       # Generate docs
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:docs    # Generate docs by specify unit paths

Editor

Start Swagger editor.

$ bundle exec rake routes:oas:editor                                                     # Start swagger editor
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:editor  # Start swagger editor by specify unit paths

UI

Start swagger ui.

$ bundle exec rake routes:oas:ui                                                         # Start swagger ui
$ PATHS_FILE="oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:ui      # Start swagger ui by specify unit paths

Build

Build docs.
Plugin is applied

$ bundle exec rake routes:oas:build

Analyze

Analyze docs.
Reads OpenAPI format document and divides it into several parts to generate a source file

$ OAS_FILE="~/Desktop/swagger.yml" bundle exec rake routes:oas:analyze

📚 Documents

Full docs are available at https://yukihirop.github.io/r2-oas

❤️ Support Rails Version

Rails 7.2.2.2
Rails (>= 8.x)

❤️ Support Ruby Version

Ruby 3.2.6
Ruby 3.3.6
Ruby (>= 3.4.x)

❤️ Support Rouging

Rails Engine Routing
Rails Normal Routing

❤️ Support OpenAPI Schema

Full docs are available at https://yukihirop.github.io/r2-oas/#/schema/3.0.0

❗️ Convention over Configuration (CoC)

tag name represents controller name and determines paths file name.
- For example, If controller name is Api::V1::UsersController, tag_name is api/v1/user, then paths file name is api/v1/user.yml
_ of components/{schemas,requestBodies, ...} name convert / when save file.
- For example, If components/schemas name is Api_V1_User, components/schemas file name is api/v1/user.yml.
- _ is supposed to be used to express namespace.
- format is Namespace1_Namespace2_Model.
. of components/{schemas,requestBodies, ...} name convert / when saving the file.
- For example, If components/schemas name is api.v1.User, components/schemas file name is api/v1/user.yml.
- . is supposed to be used to express namespace.
- format is namespace1.namespace2.Model.

⚙ Configure

All settings are optional

Full docs are available at https://yukihirop.github.io/r2-oas/#/setting/configure

Bundle and Rspec with multiple ruby versions

Bundle

/bin/bash devscript/all_support_ruby.sh bundle
.
.
.
===== Bundle install for All Support Ruby Result =====
ruby-3.2.6: 0
ruby-3.3.6: 0
ruby-3.4.7: 0
======================================================

If specify ruby version 3.2.6 and 3.3.6

/bin/bash devscript/all_support_ruby.sh bundle 3.2.6 3.3.6
.
.
.
===== Bundle install for All Support Ruby Result =====
ruby-3.2.6: 0
ruby-3.3.6: 0
======================================================

Rspec

/bin/bash devscript/all_support_ruby.sh rspec
.
.
.
===== Rspec for All Support Ruby Result =====
ruby-3.2.6: 0
ruby-3.3.6: 0
ruby-3.4.7: 0
=============================================