https://github.com/yukihirop/r2-oas
r2-oas allows generation of OpenAPI Specification (V3) from config/routes.rb in Rails application.
https://github.com/yukihirop/r2-oas
gem gems openapi openapi3 rails rest ruby
Last synced: about 1 year ago
JSON representation
r2-oas allows generation of OpenAPI Specification (V3) from config/routes.rb in Rails application.
- Host: GitHub
- URL: https://github.com/yukihirop/r2-oas
- Owner: yukihirop
- License: mit
- Created: 2019-03-14T12:51:19.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-12-22T17:00:54.000Z (over 2 years ago)
- Last Synced: 2025-04-23T11:57:50.222Z (about 1 year ago)
- Topics: gem, gems, openapi, openapi3, rails, rest, ruby
- Language: Ruby
- Homepage: https://yukihirop.github.io/r2-oas
- Size: 4.26 MB
- Stars: 15
- Watchers: 2
- Forks: 4
- Open Issues: 9
-
Metadata Files:
- Readme: README.ja.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# R2-OAS
[](https://badge.fury.io/rb/r2-oas)
[](https://travis-ci.org/yukihirop/r2-oas)
[](https://coveralls.io/github/yukihirop/r2-oas)
[](https://codeclimate.com/github/yukihirop/r2-oas/maintainability)
Railsのルーティング情報からOpenAPI形式のドキュメントを生成し、閲覧・編集・管理するためのrakeタスクの提供をします。
```bash
bundle exec rake routes:oas:init # 初期化
bundle exec rake routes:oas:docs # ドキュメント生成
bundle exec rake routes:oas:ui # ドキュメント閲覧
bundle exec rake routes:oas:editor # ドキュメント編集
bundle exec rake routes:oas:monitor # ドキュメント監視
bundle exec rake routes:oas:build # ドキュメントビルド
bundle exec rake routes:oas:clean # ドキュメント清掃
bundle exec rake routes:oas:analyze # ドキュメント分解・分析
bundle exec rake routes:oas:deploy # ドキュメントデプロイ
```
## 💎 Installation
railsアプリケーションのGemfileに以下を追加します。
```ruby
group :development do
gem 'r2-oas'
end
```
## 🔦 Requirements
もしSwaggerEditorやSwaggerUIを使ってドキュメントを閲覧・編集する場合には以下のものが必要です。
- [`swaggerapi/swagger-ui:latest` docker image](https://hub.docker.com/r/swaggerapi/swagger-ui/)
- [`swaggerapi/swagger-editor:latest` docker image](https://hub.docker.com/r/swaggerapi/swagger-editor/)
- [`chromedriver`](http://chromedriver.chromium.org/downloads)
もしダウンロードしてなかったら以下のコマンドでダウンロードできます。
```
$ docker pull swaggerapi/swagger-editor:latest
$ docker pull swaggerapi/swagger-ui:latest
$ brew cask install chromedriver
```
## 🚀 Tutorial
gemをrequire後、以下のrakeタスクを実行するだけです。
```bash
$ 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
## 📚 Documents
公式ドキュメントはこちら => https://yukihirop.github.io/r2-oas
## 📖 Usage
railsプロジェクトのルートディレクトリで以下のコマンドが実行可能です。
一般的なコマンドの使用例を示します。
### Initialize
`r2-oas`の初期化
```bash
$ 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
ドキュメントの生成
```bash
$ 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
SwaggerEditorの起動
```bash
$ 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
SwaggerUIの起動
```bash
$ 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
ドキュメントのビルド
※プラグインが適用されます。
```bash
$ bundle exec rake routes:oas:build
```
### Analyze
ドキュメントの分割
OpenAPI形式のドキュメントを読み取り、それをいくつかの部分に分割してソースファイルを生成します
```bash
$ OAS_FILE="~/Desktop/swagger.yml" bundle exec rake routes:oas:analyze
```
## ⚾️ sample
実際の使用例を見るにはこちらのリポジトリを参考にしてください。
- [yukihirop/r2oas-k8s-example](https://github.com/yukihirop/r2oas-k8s-example)
- [yukihirop/r2oas-moneyforward-example](https://github.com/yukihirop/r2oas-moneyforward-example)
- [yukihirop/r2oas-leaddesk-example](https://github.com/yukihirop/r2oas-leaddesk-example)
- [yukihirop/r2oas-advanced-example](https://github.com/yukihirop/r2oas-advanced-example)
## ❤️ 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
OpenAPIの3.0.0をサポートしてます。
公式ドキュメントはこちら => https://yukihirop.github.io/r2-oas/#/schema/3.0.0
## ❗️Convention over Configuration (CoC)
ツールを便利にするために、設定よりも制約があります。
- `タグ名` は `コントローラー名` を表しており、`pathsファイル名とパス` を決定するのに使用されます。
- 例えば、 `コントローラー名` が `Api::V1::UsersController` ならば、 `タグ名` は `api/v1/user` になります。そして、 `pathsファイル名とパス` は `api/v1/user.yml` となります。
- `components/{schemas, requestBodies, ...}名` の `_` は保存時に `/` に変換されます。hennkannsaremasu.
- 例えば、 `components/schemas名` が `Api_V1_User` なら、 `components/schemasのファイル名とパス` は `api/v1/user.yml` となります。
- フォーマットは、 `Namespace1_Namespace2_Model` です。
- `components/{schemas, requestBodies, ...}名` の `.` は保存時に `/` に変換されます。hennkannsaremasu.
- 例えば、 `components/schemas名` が `api.v1.User` なら、 `components/schemasのファイル名とパス` は `api/v1/user.yml` となります。
- フォーマットは、 `namespace1.namespace2.Model` です。
## ⚙ Configure
全ての設定は `オプショナル` です。設定してもしなくても構いません。
公式ドキュメントはこちら => https://yukihirop.github.io/r2-oas/#/setting/configure
## Bundle and Rspec with multiple ruby versions
#### Bundle
```bash
/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
======================================================
```
rubyのバージョンを `2.6.6` と `2.7.1` に指定する場合
```bash
/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
```bash
/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
=============================================
```
rubyのバージョンを `2.6.6` と `2.7.1` に指定する場合
```bash
/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
[rack-cors](https://github.com/cyu/rack-cors)を使用する事でCORSを可能にします。
```ruby
require 'rack/cors'
use Rack::Cors do
allow do
origins '*'
resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
end
end
```
`before` ブロックにCORSヘッダーを設定できます。
```ruby
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](https://opensource.org/licenses/MIT).
## 🤝 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