openapi-ruby 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7990b0f6b4af407b5df408029221d095428b91e0f0cc71f798f77e6d37901eb5
-  data.tar.gz: 4514fb71405d81e25a2e079e9e0ebcb03110f1430c327be386fd4d63c336eff1
+  metadata.gz: 5f7b5b27e899e80be2470549b5a347b3e3cd9a3d3974f8d5de3842510741e252
+  data.tar.gz: d322e9f88d6164fe4f6f10203266efa88eb99a6f7b27cf0983376bc3587d2e77
 SHA512:
-  metadata.gz: 6f2f27ba8f415683fb454b707e90eec7b9bb3f6adf5c5c1835b1f4002d83afb898414d4a735cc372d9b6a5a47f636c7aa2d0bf24dee092c5fe2b40180828a218
-  data.tar.gz: 666bb48fd0aaa60c3b25ab242e180735513416db9b34aaa22ec9dcabd54cc0dbcb2aeb5a50d36c7ae860f68fda83cb5261e0706561decce219f657fde4003853
+  metadata.gz: 1a1948211044728807f9ff02fa7a0d81af64c4d52619bbcf43895481d8309e4c949c8e40d8daff4c897d694afc53ac02fd48194fa88203bc49d5d7f102200927
+  data.tar.gz: 55a9e333eff2da6db2a8032ad3777219b8df7957f3fc49b5dafc9fc3f0cf586d35836df8439b3b40dcb09e0c2ed56b7aff6fbe7ebc67b75264bf62c1cede3cc2

data/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">openapi_ruby</h1>
 
 <p align="center">
-  A unified OpenAPI toolkit for Rails that combines test-driven spec generation, reusable schema components as Ruby classes, and runtime request/response validation middleware. Supports OpenAPI 3.0 and 3.1. Works with both RSpec and Minitest.
+  A unified OpenAPI toolkit for Rails, Hanami, and Rack that combines test-driven spec generation, reusable schema components as Ruby classes, and runtime request/response validation middleware. Supports OpenAPI 3.0 and 3.1. Works with both RSpec and Minitest.
 </p>
 
 Replaces [rswag](https://github.com/rswag/rswag), [rswag-schema-components](https://github.com/101skills-gmbh/rswag-schema-components), and [committee](https://github.com/interagent/committee) with a single gem.
@@ -14,6 +14,7 @@ Replaces [rswag](https://github.com/rswag/rswag), [rswag-schema-components](http
 
 - **OpenAPI 3.0 & 3.1** with JSON Schema 2020-12 (via [json_schemer](https://github.com/davishmcclurg/json_schemer))
 - **Test-framework agnostic** — works with RSpec and Minitest
+- **Host-framework agnostic** — works on Rails, Hanami, Sinatra, and bare Rack
 - **Schema components** as Ruby classes with inheritance
 - **Runtime middleware** for request/response validation with deep type checking
 - **Strong params** derived from schema components
@@ -23,7 +24,7 @@ Replaces [rswag](https://github.com/rswag/rswag), [rswag-schema-components](http
 ## Requirements
 
 - Ruby >= 3.2
-- Rails >= 7.0
+- Rails >= 7.0, Hanami >= 2.3, or any Rack app (see [Host Frameworks](#host-frameworks))
 
 ## Installation
 
@@ -47,6 +48,8 @@ This creates:
 - `openapi/` — output directory for generated specs
 - Engine mount in `config/routes.rb`
 
+The install generator is Rails-only — see [Host Frameworks](#host-frameworks) for the equivalent setup elsewhere.
+
 ## Configuration
 
 ```ruby
@@ -497,15 +500,29 @@ require "rails/test_help"
 # ...other test-time setup...
 ```
 
-This is purely an optimization — generation is already correct and database-free without it.
+This is purely an optimization — generation is already correct and database-free without it. Reach for it only if generation is slow enough to bother you.
 
-One caveat if you do guard: skipping `rails/test_help` also means `fixtures` is undefined, so any test file calling `fixtures :all` in its class body fails to *load*. Point `PATTERN` at just the files carrying `api_path` declarations:
+#### When guarding backfires
 
-```bash
-PATTERN="test/integration/api/**/*_test.rb" rake openapi_ruby:generate
-```
+The guard skips a require, so anything that require defines is gone for the whole generation run. That is fine for setup your files only touch while *running*, and fatal for anything they touch while *loading* — a file that fails to load contributes no declarations, and generation fails outright.
+
+Loading a spec/test file executes its class body, so these all break under a guard:
+
+- `fixtures :all` — `fixtures` is undefined without `rails/test_help`
+- `include Devise::Test::IntegrationHelpers` — needs `rspec/rails` (or `rails/test_help`) already loaded
+- `it_behaves_like "..."` / `include_examples` at the top level — needs the shared examples your helper loaded
+
+Two ways out, and they compose:
+
+1. **Narrow `PATTERN`** to just the files carrying `path` / `api_path` declarations, so the files with load-time dependencies are never loaded:
+
+   ```bash
+   PATTERN="test/integration/api/**/*_test.rb" rake openapi_ruby:generate
+   ```
 
-Suites using FactoryBot rather than fixtures don't hit this.
+2. **Leave that helper unguarded.** A helper whose constants are referenced at load time across the suite is often not worth guarding — you would be trading a working generation run for a faster one. Guarding is optional per helper; guard `test/test_helper.rb` and leave `spec/rails_helper.rb` alone if that is what your suite needs.
+
+Suites using FactoryBot rather than fixtures, and keeping helper includes inside `before` blocks, tend not to hit any of this.
 
 ### How a request finds its api_path (Style 2)
 
@@ -570,7 +587,7 @@ declares a second path. Off by default.
 
 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.
 
-Here the guards described above stop being optional: without them both test frameworks wire themselves into Rails' lazy-load hooks in the same process.
+Here the guards described above carry more weight: without them both test frameworks wire themselves into Rails' lazy-load hooks in the same process. Guard what you can — but the "When guarding backfires" rules still apply, so a helper your suite leans on at load time stays unguarded even in hybrid mode.
 
 ```ruby
 # test/test_helper.rb
@@ -590,7 +607,198 @@ end
 
 `OpenapiRuby.schema_generating?` returns `true` when the rake task launched the current process (it 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.
 
-Once the migration completes and only one test framework remains, the rake task auto-detects that framework. The guard is then no longer *required* — but it's still worth keeping for the reasons in "Making generation cheaper" above.
+Once the migration completes and only one test framework remains, the rake task auto-detects that framework, and the guard goes back to being a pure optimization.
+
+## Host Frameworks
+
+Rails picks up its wiring from the engine. Every other host makes the same calls itself — the gem only ever needs a Rack middleware stack, a way to mount a Rack app, and rack-test.
+
+| | Rails | Hanami | Sinatra / Roda / bare Rack |
+|---|---|---|---|
+| Test DSL + generation | ✅ | ✅ | ✅ |
+| Runtime validation middleware | automatic | one call | one call |
+| Schema + Swagger UI endpoints | `mount OpenapiRuby::Engine` | `mount OpenapiRuby::RackApp` | `map`/`run OpenapiRuby::RackApp` |
+| `openapi_ruby:install` / `:component` generators | ✅ | — | — |
+| `openapi_permit` strong params | ✅ | — | — |
+
+Versions covered by CI: Rails 7.0–8.0, Hanami 2.3 and 3.0, Sinatra 3.2 and 4.2. Working reference apps live in [`spec/dummy`](spec/dummy), [`spec/hanami_dummy`](spec/hanami_dummy), and [`spec/sinatra_dummy`](spec/sinatra_dummy).
+
+### Hanami
+
+**1. Configure.** Anywhere that loads before your app class — `config/openapi_ruby.rb` is a natural home:
+
+```ruby
+require "openapi_ruby/hanami"
+
+OpenapiRuby.configure do |config|
+  config.schemas = {
+    public_api: {
+      info: { title: "My API", version: "v1" },
+      servers: [{ url: "/api/v1" }],
+      prefix: "/api/v1" # scopes the validation middleware to the API
+    }
+  }
+end
+```
+
+Components default to `config/api_components/` on Hanami instead of `app/api_components/`. Zeitwerk owns everything under `app/` and expects `app/api_components/schemas/user.rb` to define `MyApp::ApiComponents::Schemas::User`, while the component loader requires the file directly — which loads fine in tests and fails on eager load in production. Keeping components outside the autoload roots avoids the clash; openapi_ruby warns if `component_paths` points inside `app/`.
+
+**2. Install the middleware** (only needed for runtime validation) in `config/app.rb`:
+
+```ruby
+require "hanami"
+require_relative "openapi_ruby"
+
+module MyApp
+  class App < Hanami::App
+    # Declared before :body_parser so the validation middleware reads and
+    # rewinds the request body first.
+    OpenapiRuby::Hanami.install_middleware!(config)
+
+    config.middleware.use :body_parser, :json
+  end
+end
+```
+
+**3. Mount the docs endpoints** in `config/routes.rb`:
+
+```ruby
+module MyApp
+  class Routes < Hanami::Routes
+    mount OpenapiRuby::RackApp, at: "/api-docs"
+  end
+end
+```
+
+For request specs, `require "openapi_ruby/rspec"` wires rack-test into `type: :openapi` example groups and points it at `Hanami.app`:
+
+```ruby
+# spec/spec_helper.rb
+ENV["HANAMI_ENV"] ||= "test"
+
+require "hanami/prepare"
+require "openapi_ruby/rspec"
+```
+
+Define `let(:app)` in a group to drive a slice instead of the whole app.
+
+### Sinatra, Roda, and bare Rack
+
+Nothing here is Sinatra-specific — it is the same three steps against a plain Rack app.
+
+**1. Configure**, and say where components live. There is no autoload convention to infer one from:
+
+```ruby
+# config/openapi_ruby.rb
+require "openapi_ruby"
+
+OpenapiRuby.configure do |config|
+  config.schemas = {
+    public_api: {
+      info: { title: "My API", version: "v1" },
+      servers: [{ url: "/api/v1" }],
+      prefix: "/api/v1"
+    }
+  }
+
+  config.component_paths = ["api_components"]
+end
+```
+
+**2. Install the middleware** onto the app's stack. `Installer#install!` takes anything that responds to `use`, which a `Sinatra::Base` subclass does:
+
+```ruby
+class App < Sinatra::Base
+  OpenapiRuby::Middleware::Installer.install!(self, root: __dir__)
+
+  # ... routes
+end
+```
+
+For Roda or bare Rack, hand it the builder instead — `OpenapiRuby::Middleware::Installer.install!(builder, root: __dir__)` inside `Rack::Builder.new { ... }`.
+
+**3. Mount the docs endpoints** in `config.ru`:
+
+```ruby
+require_relative "app"
+
+map "/api-docs" do
+  run OpenapiRuby::RackApp
+end
+
+map "/" do
+  run App
+end
+```
+
+For request specs, `require "openapi_ruby/rspec"` includes rack-test for you; naming the app is the only wiring left, since no Rack host has a convention for which app is under test:
+
+```ruby
+# spec/spec_helper.rb
+ENV["APP_ENV"] ||= "test"
+
+require_relative "../app"
+require "openapi_ruby/rspec"
+
+module AppUnderTest
+  def app
+    App
+  end
+end
+
+RSpec.configure do |config|
+  config.include AppUnderTest, type: :openapi
+end
+```
+
+Minitest is the same shape — including the DSL brings rack-test with it, and the class defines `app`:
+
+```ruby
+class ApiTest < Minitest::Test
+  include OpenapiRuby::Adapters::Minitest::DSL
+
+  def app
+    App
+  end
+end
+```
+
+> **Getting 403 "Host not permitted"?** Sinatra only relaxes its host authorization outside `development`, and rack-test sends `Host: example.org`. Set `APP_ENV=test` (or `RACK_ENV=test`) in your test helper — the snippet above does.
+
+### Specs and generation on every host
+
+Specs are written identically regardless of host, in either DSL style:
+
+```ruby
+RSpec.describe "Posts API", type: :openapi do
+  openapi_schema :public_api
+
+  api_path "/posts" do
+    get "List posts" do
+      tags "Posts"
+      produces "application/json"
+
+      response 200, "returns posts" do
+        schema type: :array, items: { "$ref" => "#/components/schemas/Post" }
+      end
+    end
+  end
+
+  it "returns all posts" do
+    assert_api_response :get, 200 do
+      expect(parsed_body.length).to eq(2)
+    end
+  end
+end
+```
+
+The Rails engine loads the rake task on its own. Elsewhere, add it to your Rakefile:
+
+```ruby
+require "openapi_ruby/rake_tasks"
+```
+
+`bundle exec rake openapi_ruby:generate` then behaves as it does on Rails. It detects the host and sets the environment variable that host reads — `RAILS_ENV`, `HANAMI_ENV`, or `APP_ENV`/`RACK_ENV` — for the generation subprocess.
 
 ## Runtime Middleware
 
@@ -632,7 +840,7 @@ Mount the engine to expose the schema endpoints:
 mount OpenapiRuby::Engine => "/api-docs"
 ```
 
-Schema files are served at `/api-docs/schemas/:name`.
+Schema files are served at `/api-docs/schemas/:name`. On any other host, mount `OpenapiRuby::RackApp` instead — see [Host Frameworks](#host-frameworks).
 
 To also serve the interactive Swagger UI at the mount root, opt in:
 

data/Rakefile

@@ -5,4 +5,36 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+# Each alternate host's dummy app runs in its own bundle, so Rails and the
+# other framework never have to boot in one process.
+#
+# Unbundled: Bundler exports BUNDLE_LOCKFILE next to BUNDLE_GEMFILE, and an
+# inherited one makes the child write its resolution into this bundle's
+# Gemfile.lock.
+def run_dummy_app_specs(gemfile, dir, command)
+  gemfile_path = File.expand_path("gemfiles/#{gemfile}", __dir__)
+
+  Bundler.with_unbundled_env do
+    Dir.chdir(dir) do
+      sh({"BUNDLE_GEMFILE" => gemfile_path}, command)
+    end
+  end
+end
+
+namespace :spec do
+  desc "Run the Hanami dummy app's specs in the Rails-free bundle"
+  task :hanami do
+    run_dummy_app_specs("hanami.gemfile", "spec/hanami_dummy", "bundle exec rspec")
+  end
+
+  desc "Run the Sinatra dummy app's specs and tests in the Rails-free bundle"
+  task :sinatra do
+    run_dummy_app_specs("sinatra.gemfile", "spec/sinatra_dummy", "bundle exec rspec")
+    run_dummy_app_specs("sinatra.gemfile", "spec/sinatra_dummy", "bundle exec ruby -Itest test/posts_test.rb")
+  end
+
+  desc "Run every host's dummy app suite"
+  task hosts: %i[hanami sinatra]
+end
+
 task default: :spec

data/app/controllers/openapi_ruby/schemas_controller.rb

@@ -3,56 +3,15 @@
 module OpenapiRuby
   class SchemasController < ActionController::API
     def show
-      schema_name = params[:id]
-      config = OpenapiRuby.configuration
+      document = Serving.schema_document(params[:id], request: request)
+      return head :not_found unless document
 
-      schema_config = config.schemas[schema_name.to_sym]
-      return head :not_found unless schema_config
-
-      file_path = schema_file_path(schema_name)
-      return head :not_found unless file_path && File.exist?(file_path)
-
-      content = File.read(file_path)
-
-      # Apply filter if configured
-      if schema_config[:openapi_filter]
-        doc = parse_content(file_path, content)
-        schema_config[:openapi_filter].call(doc, request)
-        content = serialize_doc(file_path, doc)
-      end
-
-      content_type = file_path.end_with?(".json") ? "application/json" : "application/x-yaml"
+      content, content_type = document
       render plain: content, content_type: content_type
     end
 
     def index
-      schemas = OpenapiRuby.configuration.schemas.keys.map(&:to_s)
-      render json: {schemas: schemas}
-    end
-
-    private
-
-    def schema_file_path(schema_name)
-      config = OpenapiRuby.configuration
-      ext = (config.schema_output_format == :json) ? "json" : "yaml"
-      path = Rails.root.join(config.schema_output_dir, "#{schema_name}.#{ext}")
-      path.to_s
-    end
-
-    def parse_content(file_path, content)
-      if file_path.end_with?(".json")
-        JSON.parse(content)
-      else
-        YAML.safe_load(content, permitted_classes: [Date, Time])
-      end
-    end
-
-    def serialize_doc(file_path, doc)
-      if file_path.end_with?(".json")
-        JSON.pretty_generate(doc)
-      else
-        doc.to_yaml
-      end
+      render json: {schemas: Serving.schema_names}
     end
   end
 end

data/app/controllers/openapi_ruby/ui_controller.rb

@@ -5,83 +5,26 @@ module OpenapiRuby
     layout false
 
     def index
-      config = OpenapiRuby.configuration
-      @schemas = config.schemas
-      @ui_config = config.ui_config
-
-      render html: swagger_ui_html.html_safe
+      html = Serving.swagger_ui_html(
+        schema_urls: schema_urls,
+        ui_config: OpenapiRuby.configuration.ui_config
+      )
+      render html: html.html_safe
     end
 
     def oauth2_redirect
-      file = File.join(OpenapiRuby::Engine.root, "app", "views", "openapi_ruby", "oauth2_redirect.html")
-      render file: file, layout: false, content_type: "text/html"
+      render file: Serving.oauth2_redirect_file, layout: false, content_type: "text/html"
     end
 
     private
 
-    def schema_format
-      (OpenapiRuby.configuration.schema_output_format == :json) ? :json : :yaml
-    end
-
-    def swagger_ui_html
-      <<~HTML
-        <!DOCTYPE html>
-        <html lang="en">
-        <head>
-          <meta charset="UTF-8">
-          <title>#{@ui_config[:title] || "API Documentation"}</title>
-          <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
-          <style>
-            html { box-sizing: border-box; overflow-y: scroll; }
-            *, *:before, *:after { box-sizing: inherit; }
-            body { margin: 0; background: #fafafa; }
-          </style>
-        </head>
-        <body>
-          <div id="swagger-ui"></div>
-          <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
-          <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
-          <script>
-            SwaggerUIBundle({
-              #{schema_urls_js},
-              dom_id: '#swagger-ui',
-              deepLinking: true,
-              presets: [
-                SwaggerUIBundle.presets.apis,
-                SwaggerUIStandalonePreset
-              ],
-              plugins: [
-                SwaggerUIBundle.plugins.DownloadUrl
-              ],
-              layout: "#{(@schemas.size > 1) ? "StandaloneLayout" : "BaseLayout"}",
-              #{ui_config_js}
-            });
-          </script>
-        </body>
-        </html>
-      HTML
-    end
-
-    def schema_urls_js
-      fmt = schema_format
-      if @schemas.size > 1
-        urls = @schemas.map { |name, schema_config|
-          title = schema_config.dig(:info, :title) || name.to_s
-          url = openapi_ruby.schema_path(name.to_s, format: fmt)
-          {url: url, name: title}
+    def schema_urls
+      OpenapiRuby.configuration.schemas.map do |name, schema_config|
+        {
+          url: openapi_ruby.schema_path(name.to_s, format: Serving.schema_format),
+          name: schema_config.dig(:info, :title) || name.to_s
         }
-        "urls: #{urls.to_json}"
-      else
-        name = @schemas.keys.first.to_s
-        url = openapi_ruby.schema_path(name, format: fmt)
-        "url: \"#{url}\""
       end
     end
-
-    def ui_config_js
-      @ui_config.except(:title).map { |k, v|
-        "#{k}: #{v.to_json}"
-      }.join(",\n          ")
-    end
   end
 end

data/lib/openapi_ruby/adapters/minitest.rb

@@ -13,6 +13,21 @@ module OpenapiRuby
           base.extend ClassMethods
           base.class_attribute :_openapi_contexts, default: []
           base.class_attribute :_openapi_schema_name, default: nil
+
+          install_rack_test!(base)
+        end
+
+        # On Rails the test class already inherits ActionDispatch's integration
+        # helpers. Every other host drives requests through rack-test, and the
+        # class defines `app` itself.
+        def self.install_rack_test!(base)
+          return if OpenapiRuby.rails_host?
+          return if base.method_defined?(:last_response)
+
+          require "rack/test"
+          base.include ::Rack::Test::Methods
+        rescue LoadError
+          nil
         end
 
         module ClassMethods
@@ -111,18 +126,18 @@ module OpenapiRuby
             assert req_errors.empty?, "Request validation failed:\n#{req_errors.join("\n")}"
           end
 
-          send(method, path, **request_args)
+          openapi_transport.dispatch(method, path, **request_args)
 
           # Validate response
-          assert_equal expected_status, response.status,
-            "Expected status #{expected_status}, got #{response.status}\nResponse body: #{response.body}"
+          assert_equal expected_status, openapi_response.status,
+            "Expected status #{expected_status}, got #{openapi_response.status}\nResponse body: #{openapi_response.body}"
 
           if response_ctx.schema_definition
             validator = Testing::ResponseValidator.new
             body_data = parse_response_body
             errors = validator.validate(
               response_body: body_data,
-              status_code: response.status,
+              status_code: openapi_response.status,
               response_context: response_ctx
             )
             assert errors.empty?, "Response validation failed:\n#{errors.join("\n")}"
@@ -136,6 +151,17 @@ module OpenapiRuby
           parse_response_body
         end
 
+        # The seam between the DSL and the host's request API. Public so specs
+        # that drive requests themselves (rate limiting, pagination loops) can
+        # reach the same dispatcher and response the assertions use.
+        def openapi_transport
+          @openapi_transport ||= Testing::Transport.for(self)
+        end
+
+        def openapi_response
+          openapi_transport.response
+        end
+
         private
 
         def find_context_for(method, path_params, params, expected_status, api_path)
@@ -222,11 +248,11 @@ module OpenapiRuby
         end
 
         def parse_response_body
-          return nil if response.body.empty?
+          return nil if openapi_response.body.empty?
 
-          JSON.parse(response.body)
+          JSON.parse(openapi_response.body)
         rescue JSON::ParserError
-          response.body
+          openapi_response.body
         end
       end