Project

r2-oas

0.01
No release in over 3 years
Low commit activity in last 3 years
r2-oasyukihirop/r2-oasHomepageDocumentationSource CodeBug TrackerWiki
== Let's intuitively write API documentation with Swagger Editor in your Rails Project! 😊 Configureless and no DSL. 👍 But you can also configure. Manage with yaml file instead of Ruby code. Loosely coupled to your Rails project. 👍 So if you want to use another tool, you can port it right away. 😢 Generate api docment(OpenAPI) side only from `Rails` routing. Provide rake tasks to management API Docment (OpenAPI) 🎉 $ 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 Happy Coding ❗️
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
40,734
Stars
15
Forks
4
Watchers
1
 Releases
Current version
0.6.0
Total releases
13
First release
1980-01-02
Latest release
2021-01-29
 Issues
Open Issues
10
Closed Issues
34
Total Issues
44
Issue Closure Rate
77%
 Pull Requests
Open Pull Requests
6
Closed Pull Requests
7
Merged Pull Requests
144
Pull Request Acceptance Rate
91%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2021-12-30
Reverse Dependencies
0

 Dependencies

Runtime

docker-api
~> 2.4
easy_diff
~> 1.0, >= 1.0.0
key_flatten
~> 1.0, >= 1.0.0
railties
>= 7.2.0, < 11.0
watir
>= 6.16.5, < 8.0
 Project Readme

Gem Version Build Status Coverage Status Maintainability

logo

R2-OAS

📚 Documentation

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

oas_docs.mp4

Edit docs

oas_editor.mp4

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

RBS, Steep

# Errors here can prevent type information from showing when hovering in the editor
bundle exec steep stats
# You can check the error details with this command
bundle exec steep check

steep rake task

bundle exec rake steep:ignore:dig | pbcopy
# =>
#
# ignore 'RBS::DuplicatedMethodDefinition'
# ignore 'Ruby::ArgumentTypeMismatch'
bundle exec rake steep:ignore:file | pbcopy
# =>
#
# ignore 'lib/r2-oas.rb'
# ignore 'lib/r2-oas/app_configuration.rb'
# ignore 'lib/r2-oas/app_configuration/deprecation.rb'
bundle exec rake steep:ignore:preview
# =>
# 📄 lib/r2-oas/schema/monitor.rb
#   Line 50: if current_time - last_check_time >= interval_to_save_edited_tmp_schema
#               →           if current_time - last_check_time >= interval_to_save_edited_tmp_schema # steep:ignore Ruby::NoMethod
#   Line 62: analyzer.analyze_docs
#               →         analyzer.analyze_docs # steep:ignore Ruby::NoMethod
#   Line 66: YAML.load_file(doc_save_file_path) || @after_schema_data
#               →         YAML.load_file(doc_save_file_path) || @after_schema_data # steep:ignore Ruby::UnknownConstant
bundle exec rake steep:ignore:auto
# =>
# Analyzing steep check errors...
# ✅ Modified: lib/r2-oas/app_configuration/deprecation.rb (2 lines)
# ✅ Modified: lib/r2-oas/plugin/base.rb (3 lines)
# ✅ Modified: lib/r2-oas/schema/squeezer.rb (2 lines)

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
=============================================

If specify ruby version 3.2.6 and 3.3.6

/bin/bash devscript/all_support_ruby.sh rspec 3.2.6 3.3.6
.
.
.
===== Rspec for All Support Ruby Result =====
ruby-3.2.6: 0
ruby-3.3.6: 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