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    # initialize
bundle exec rake routes:oas:docs    # generate
bundle exec rake routes:oas:ui      # view
bundle exec rake routes:oas:editor  # edit
bundle exec rake routes:oas:monitor # monitor
bundle exec rake routes:oas:build   # build
bundle exec rake routes:oas:clean   # clean
bundle exec rake routes:oas:analyze # analyze
bundle exec rake routes:oas:deploy  # deploy

💎 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:

• swaggerapi/swagger-ui:latest docker image
• swaggerapi/swagger-editor:latest docker image
• chromedriver

If you do not have it download as below.

$ docker pull swaggerapi/swagger-editor:latest
$ docker pull swaggerapi/swagger-ui:latest
$ brew cask 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

Edit docs

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 (>= 4.2.5.1)

❤️ Support Ruby Version

• Ruby (>= 2.5.0)

❤️ 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-2.5.8: 0
ruby-2.6.6: 0
ruby-2.7.1: 0
======================================================

If specify ruby version 2.6.6 and 2.7.1

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

Rspec

/bin/bash devscript/all_support_ruby.sh rspec
.
.
.
===== Rspec for All Support Ruby Result =====
ruby-2.5.8: 0
ruby-2.6.6: 0
ruby-2.7.1: 0
=============================================

If specify ruby version 2.6.6 and 2.7.1

/bin/bash devscript/all_support_ruby.sh rspec 2.6.6 2.7.1
.
.
.
===== Rspec for All Support Ruby Result =====
ruby-2.6.6: 0
ruby-2.7.1: 0
=============================================

🔩 CORS

Use rack-cors to enable CORS.

require 'rack/cors'
use Rack::Cors do
  allow do
    origins '*'
    resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
  end
end

Alternatively, you can set CORS headers in a before block.

before do
  header['Access-Control-Allow-Origin'] = '*'
  header['Access-Control-Request-Method'] = '*'
end

📝 License

The gem is available as open source under the terms of the MIT License.

🤝 Contributing

1. Fork it ( http://github.com/yukihirop/r2-oas/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request