openapi-ruby 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e97365e4c2b566d59db1f4946a2b0e1f45f8ee9b938f2b5c049ac0ac9f56dcc
-  data.tar.gz: 431709a674d6a028fd8a14f47200761215a6e4576888009b3b2b637fd5a453b9
+  metadata.gz: b58ff6e6c8ccbf7c8c02d01f6a79ea02717cf3c709de9d1c8a8f870bb44a84fb
+  data.tar.gz: e18b82cac3cd08bee2fcbee279d45e9b705b62ad0015feb8e3e5408cf4af63a5
 SHA512:
-  metadata.gz: 0a670b21d1043c474b2eead1844c47258521df05b247d561a5578de4c8495a6519b575c7b3d2d4fe4fc54c22d5d524e45ee2fab492e99e3366c8eab5bc381ecf
-  data.tar.gz: e2981bfa965fef6c6db6767d8e36592b8166fa20f675265c9d0147265565250e845093ca4fb3dc3bd3a7d2a2b1c3a7c6cb9d52169a0142bc0be2a90727a50b77
+  metadata.gz: d9248a97e6b5f513516f5d97d87ef81f68047ce4db54c62503667d20751bf15f99fb4644cde3369d017b388184e92e65f904aa171e546c189134d8d1dc742eea
+  data.tar.gz: 4a627ed1b9bc867c24263627a27f01f22d5fc50bfde5ffe9d93e87484c50e68f61e739162c198c808b979d484c9c1a3b80921c14eedd32a9c7b076a702a90cb9

data/README.md

@@ -193,6 +193,31 @@ class Schemas::AdminUser
 end
 ```
 
+### Class References
+
+Instead of writing `$ref` strings manually, you can pass component classes directly anywhere a `$ref` is expected. This gives you typo protection (via `NameError`), IDE navigation, and less boilerplate:
+
+```ruby
+# Instead of:
+schema "$ref" => "#/components/schemas/User"
+schema type: :array, items: { "$ref" => "#/components/schemas/User" }
+
+# You can write:
+schema Schemas::User
+schema type: :array, items: Schemas::User
+```
+
+This works in `schema`, `request_body`, and anywhere nested inside hash/array definitions. Non-component classes raise `ArgumentError`.
+
+You can also use the explicit `.to_ref` method:
+
+```ruby
+Schemas::User.to_ref
+# => { "$ref" => "#/components/schemas/User" }
+```
+
+Both class refs and string `$ref` hashes are fully supported — use whichever you prefer.
+
 ### Strong Params
 
 Schema components can derive Rails strong params permit lists:
@@ -252,7 +277,7 @@ RSpec.describe "Users API", type: :openapi do
       produces "application/json"
 
       response 200, "returns all users" do
-        schema type: :array, items: { "$ref" => "#/components/schemas/User" }
+        schema type: :array, items: Schemas::User
 
         run_test! do
           expect(JSON.parse(response.body).length).to be > 0
@@ -265,19 +290,17 @@ RSpec.describe "Users API", type: :openapi do
       consumes "application/json"
 
       request_body required: true, content: {
-        "application/json" => {
-          schema: { "$ref" => "#/components/schemas/UserInput" }
-        }
+        "application/json" => { schema: Schemas::UserInput }
       }
 
       response 201, "user created" do
-        schema "$ref" => "#/components/schemas/User"
+        schema Schemas::User
         let(:request_body) { { name: "Jane", email: "jane@example.com" } }
         run_test!
       end
 
       response 422, "validation errors" do
-        schema "$ref" => "#/components/schemas/ValidationErrors"
+        schema Schemas::ValidationErrors
         let(:request_body) { { name: "" } }
         run_test!
       end
@@ -289,7 +312,7 @@ RSpec.describe "Users API", type: :openapi do
 
     get "Get a user" do
       response 200, "user found" do
-        schema "$ref" => "#/components/schemas/User"
+        schema Schemas::User
         let(:id) { User.create!(name: "Jane", email: "jane@example.com").id }
         run_test!
       end
@@ -319,7 +342,7 @@ RSpec.describe "Users API", type: :openapi do
       produces "application/json"
 
       response 200, "returns all users" do
-        schema type: :array, items: { "$ref" => "#/components/schemas/User" }
+        schema type: :array, items: Schemas::User
       end
     end
 
@@ -327,17 +350,15 @@ RSpec.describe "Users API", type: :openapi do
       consumes "application/json"
 
       request_body required: true, content: {
-        "application/json" => {
-          schema: { "$ref" => "#/components/schemas/UserInput" }
-        }
+        "application/json" => { schema: Schemas::UserInput }
       }
 
       response 201, "user created" do
-        schema "$ref" => "#/components/schemas/User"
+        schema Schemas::User
       end
 
       response 422, "validation errors" do
-        schema "$ref" => "#/components/schemas/ValidationErrors"
+        schema Schemas::ValidationErrors
       end
     end
   end
@@ -407,7 +428,7 @@ class UsersApiTest < ActionDispatch::IntegrationTest
       produces "application/json"
 
       response 200, "returns all users" do
-        schema type: :array, items: { "$ref" => "#/components/schemas/User" }
+        schema type: :array, items: Schemas::User
       end
     end
 
@@ -415,13 +436,11 @@ class UsersApiTest < ActionDispatch::IntegrationTest
       consumes "application/json"
 
       request_body required: true, content: {
-        "application/json" => {
-          schema: { "$ref" => "#/components/schemas/UserInput" }
-        }
+        "application/json" => { schema: Schemas::UserInput }
       }
 
       response 201, "user created" do
-        schema "$ref" => "#/components/schemas/User"
+        schema Schemas::User
       end
     end
   end
@@ -450,10 +469,34 @@ Generate OpenAPI spec files without running tests:
 rake openapi_ruby:generate
 ```
 
-This loads spec/test files to collect API definitions and writes schemas without running any tests. It auto-detects the test framework, or you can set `FRAMEWORK=rspec` or `FRAMEWORK=minitest`. Custom patterns: `PATTERN="packs/*/spec/**/*_spec.rb"`.
+This loads spec/test files to collect API definitions and writes schemas without running any tests. It auto-detects the test framework, or you can set `FRAMEWORK=rspec`, `FRAMEWORK=minitest`, or `FRAMEWORK=hybrid`. Custom patterns: `PATTERN="packs/*/spec/**/*_spec.rb"`.
 
 Schemas are **only** written by the rake task — running tests (`bundle exec rspec`, `rails test`) does not generate or overwrite schema files. This prevents partial schema overwrites when running a subset of specs.
 
+### Migrating from RSpec to Minitest (or vice versa)
+
+When both `spec/spec_helper.rb` and `test/test_helper.rb` are present, the rake task auto-selects `FRAMEWORK=hybrid` — it requires both adapters and loads both glob patterns (`spec/**/*_spec.rb,test/**/*_test.rb`) into one process. Style 1 `path(...)` and Style 2 `api_path(...)` definitions register into the same `MetadataStore`, so a single schema file holds paths contributed by either DSL.
+
+Two things to set up on the consumer side so the two test frameworks don't both wire themselves into Rails' lazy-load hooks during schema generation:
+
+```ruby
+# test/test_helper.rb
+unless ENV["OPENAPI_RUBY_GENERATING"]
+  require "rails/test_help"
+  # ...other test-time setup...
+end
+```
+
+```ruby
+# spec/rails_helper.rb
+unless ENV["OPENAPI_RUBY_GENERATING"]
+  require "rspec/rails"
+  # ...other spec-time setup...
+end
+```
+
+The rake task sets `OPENAPI_RUBY_GENERATING=true` in the subprocess. With the guards in place, neither test framework boots its full Rails integration during generation — only the DSL needs to be live for `api_path` / `path` to register.
+
 ## Runtime Middleware
 
 Validate requests and responses against your OpenAPI spec at runtime:

data/lib/openapi_ruby/components/base.rb

@@ -85,6 +85,10 @@ module OpenapiRuby
           end
         end
 
+        def to_ref
+          OpenapiRuby::Core::RefResolver.ref_object(_component_type, component_name)
+        end
+
         def to_openapi
           definition = _schema_definition.deep_dup
 
@@ -147,6 +151,12 @@ module OpenapiRuby
 
         def deep_stringify(value)
           case value
+          when Class
+            if value < OpenapiRuby::Components::Base
+              value.to_ref
+            else
+              raise ArgumentError, "#{value} is not an OpenapiRuby component"
+            end
           when Hash
             value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
           when Array

data/lib/openapi_ruby/dsl/context.rb

@@ -45,6 +45,12 @@ module OpenapiRuby
 
       def deep_stringify(value)
         case value
+        when Class
+          if value < OpenapiRuby::Components::Base
+            value.to_ref
+          else
+            raise ArgumentError, "#{value} is not an OpenapiRuby component"
+          end
         when Hash
           value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
         when Array

data/lib/openapi_ruby/dsl/operation_context.rb

@@ -128,6 +128,12 @@ module OpenapiRuby
 
       def deep_stringify(value)
         case value
+        when Class
+          if value < OpenapiRuby::Components::Base
+            value.to_ref
+          else
+            raise ArgumentError, "#{value} is not an OpenapiRuby component"
+          end
         when Hash
           value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
         when Array

data/lib/openapi_ruby/dsl/response_context.rb

@@ -72,6 +72,12 @@ module OpenapiRuby
 
       def deep_stringify(value)
         case value
+        when Class
+          if value < OpenapiRuby::Components::Base
+            value.to_ref
+          else
+            raise ArgumentError, "#{value} is not an OpenapiRuby component"
+          end
         when Hash
           value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
         when Array

data/lib/openapi_ruby/generator/rake_task_support.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Generator
+    # Helpers backing the `openapi_ruby:generate` rake task. Extracted
+    # so the framework detection / script generation logic is testable
+    # without booting Rake.
+    module RakeTaskSupport
+      module_function
+
+      def detect_test_framework
+        rspec = File.exist?("spec/spec_helper.rb") || File.exist?("spec/rails_helper.rb")
+        minitest = File.exist?("test/test_helper.rb")
+
+        if rspec && minitest
+          "hybrid"
+        elsif rspec
+          "rspec"
+        elsif minitest
+          "minitest"
+        else
+          raise ArgumentError,
+            "Could not detect test framework. Set FRAMEWORK=rspec, FRAMEWORK=minitest, or FRAMEWORK=hybrid."
+        end
+      end
+
+      def default_pattern_for(framework)
+        case framework
+        when "rspec" then "spec/**/*_spec.rb"
+        when "minitest" then "test/**/*_test.rb"
+        when "hybrid" then "spec/**/*_spec.rb,test/**/*_test.rb"
+        end
+      end
+
+      def generate_script(framework, pattern)
+        case framework
+        when "rspec" then rspec_script(pattern)
+        when "minitest" then minitest_script(pattern)
+        when "hybrid" then hybrid_script(pattern)
+        else
+          raise ArgumentError, "Unknown test framework '#{framework}'."
+        end
+      end
+
+      def rspec_script(pattern)
+        <<~RUBY
+          require "rspec/core"
+          $LOAD_PATH.unshift(File.expand_path("spec")) unless $LOAD_PATH.include?(File.expand_path("spec"))
+          #{glob_loads(pattern)}
+          OpenapiRuby::Generator::SchemaWriter.generate_all!
+        RUBY
+      end
+
+      def minitest_script(pattern)
+        <<~RUBY
+          require "openapi_ruby/minitest"
+          #{glob_loads(pattern)}
+          OpenapiRuby::Generator::SchemaWriter.generate_all!
+        RUBY
+      end
+
+      # Loads both adapters and both file globs in one process. Useful
+      # during a phased RSpec → Minitest migration where the suite
+      # holds both DSL styles. Consumers should guard
+      # `require "rails/test_help"` and `require "rspec/rails"` in
+      # their test helpers with `unless ENV["OPENAPI_RUBY_GENERATING"]`
+      # so the two test frameworks don't both register Rails lazy
+      # hooks in the same process — only the DSL needs to be live for
+      # schema generation.
+      def hybrid_script(pattern)
+        <<~RUBY
+          require "rspec/core"
+          require "openapi_ruby/rspec"
+          require "openapi_ruby/minitest"
+          $LOAD_PATH.unshift(File.expand_path("spec")) unless $LOAD_PATH.include?(File.expand_path("spec"))
+          $LOAD_PATH.unshift(File.expand_path("test")) unless $LOAD_PATH.include?(File.expand_path("test"))
+          #{glob_loads(pattern)}
+          OpenapiRuby::Generator::SchemaWriter.generate_all!
+        RUBY
+      end
+
+      def glob_loads(pattern)
+        pattern.split(",").map do |p|
+          %[Dir.glob(#{p.strip.inspect}).sort.each { |f| require File.expand_path(f) }]
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/openapi_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiRuby
-  VERSION = "3.2.0"
+  VERSION = "3.4.0"
 end

data/lib/openapi_ruby.rb

@@ -47,6 +47,7 @@ require_relative "openapi_ruby/testing/request_validator"
 require_relative "openapi_ruby/testing/assertions"
 require_relative "openapi_ruby/testing/coverage"
 require_relative "openapi_ruby/generator/schema_writer"
+require_relative "openapi_ruby/generator/rake_task_support"
 require_relative "openapi_ruby/middleware/path_matcher"
 require_relative "openapi_ruby/middleware/coercion"
 require_relative "openapi_ruby/middleware/error_handler"

data/lib/tasks/openapi_ruby.rake

@@ -1,55 +1,21 @@
 # frozen_string_literal: true
 
+require "openapi_ruby/generator/rake_task_support"
+
 namespace :openapi_ruby do
   desc "Generate OpenAPI schema files from spec definitions and components"
   task :generate do
-    framework = ENV.fetch("FRAMEWORK", detect_test_framework).to_s
-    pattern = ENV.fetch("PATTERN", default_pattern_for(framework))
+    support = OpenapiRuby::Generator::RakeTaskSupport
+    framework = ENV.fetch("FRAMEWORK") { support.detect_test_framework }.to_s
+    pattern = ENV.fetch("PATTERN") { support.default_pattern_for(framework) }
 
     # Spawn a subprocess so RAILS_ENV defaults to "test" cleanly,
     # just like rswag did with RSpec::Core::RakeTask.
     env = {"RAILS_ENV" => ENV.fetch("RAILS_ENV", "test"), "OPENAPI_RUBY_GENERATING" => "true"}
-    script = generate_script(framework, pattern)
+    script = support.generate_script(framework, pattern)
     command = "bundle exec ruby -e #{Shellwords.escape(script)}"
 
     puts "Generating OpenAPI schemas (#{framework})..."
     system(env, command) || abort("Schema generation failed")
   end
 end
-
-def detect_test_framework
-  if File.exist?("spec/spec_helper.rb") || File.exist?("spec/rails_helper.rb")
-    "rspec"
-  elsif File.exist?("test/test_helper.rb")
-    "minitest"
-  else
-    abort "Could not detect test framework. Set FRAMEWORK=rspec or FRAMEWORK=minitest."
-  end
-end
-
-def default_pattern_for(framework)
-  case framework
-  when "rspec" then "spec/**/*_spec.rb"
-  when "minitest" then "test/**/*_test.rb"
-  end
-end
-
-def generate_script(framework, pattern)
-  case framework
-  when "rspec"
-    <<~RUBY
-      require "rspec/core"
-      $LOAD_PATH.unshift(File.expand_path("spec")) unless $LOAD_PATH.include?(File.expand_path("spec"))
-      #{pattern.split(",").map { |p| %[Dir.glob(#{p.strip.inspect}).sort.each { |f| require File.expand_path(f) }] }.join("\n")}
-      OpenapiRuby::Generator::SchemaWriter.generate_all!
-    RUBY
-  when "minitest"
-    <<~RUBY
-      require "openapi_ruby/minitest"
-      #{pattern.split(",").map { |p| %[Dir.glob(#{p.strip.inspect}).sort.each { |f| require File.expand_path(f) }] }.join("\n")}
-      OpenapiRuby::Generator::SchemaWriter.generate_all!
-    RUBY
-  else
-    abort "Unknown test framework '#{framework}'."
-  end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Morten Hartvig
@@ -105,6 +105,7 @@ files:
 - lib/openapi_ruby/dsl/response_context.rb
 - lib/openapi_ruby/engine.rb
 - lib/openapi_ruby/errors.rb
+- lib/openapi_ruby/generator/rake_task_support.rb
 - lib/openapi_ruby/generator/schema_writer.rb
 - lib/openapi_ruby/middleware/coercion.rb
 - lib/openapi_ruby/middleware/error_handler.rb