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 imageswaggerapi/swagger-editor:latest
docker imagechromedriver
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
representscontroller name
and determinespaths file name
.- For example, If
controller name
isApi::V1::UsersController
,tag_name
isapi/v1/user
, thenpaths file name
isapi/v1/user.yml
- For example, If
-
_
ofcomponents/{schemas,requestBodies, ...} name
convert/
when save file.- For example, If
components/schemas name
isApi_V1_User
,components/schemas file name
isapi/v1/user.yml
. -
_
is supposed to be used to expressnamespace
. - format is
Namespace1_Namespace2_Model
.
- For example, If
-
.
ofcomponents/{schemas,requestBodies, ...} name
convert/
when saving the file.- For example, If
components/schemas name
isapi.v1.User
,components/schemas file name
isapi/v1/user.yml
. -
.
is supposed to be used to expressnamespace
. - format is
namespace1.namespace2.Model
.
- For example, If
β 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
- Fork it ( http://github.com/yukihirop/r2-oas/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request