openapi-ruby 4.1.0 → 5.0.0

data/lib/openapi_ruby/rack_app.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module OpenapiRuby
+  # Serves the generated schema documents and the Swagger UI as a plain Rack
+  # app, for hosts with no engine to mount:
+  #
+  #   # Hanami — config/routes.rb
+  #   mount OpenapiRuby::RackApp, at: "/api-docs"
+  #
+  # Routes mirror the Rails engine's (config/routes.rb) so both hosts expose
+  # the same paths. Schema URLs are derived from SCRIPT_NAME, so the app works
+  # at any mount point.
+  #
+  # Deliberately not namespaced under OpenapiRuby::Rack: that constant would
+  # shadow the top-level ::Rack for every file in this gem.
+  class RackApp
+    SCHEMA_PATH = %r{\A/schemas/(?<name>.+)\z}
+    SCHEMA_EXTENSION = /\.(json|ya?ml)\z/
+
+    def self.call(env)
+      (@app ||= new).call(env)
+    end
+
+    def call(env)
+      request = ::Rack::Request.new(env)
+      return method_not_allowed unless request.get? || request.head?
+
+      status, headers, body = case request.path_info
+      when "", "/" then ui(request)
+      when "/schemas" then schema_index
+      when "/oauth2-redirect.html" then oauth2_redirect
+      when SCHEMA_PATH then schema(::Regexp.last_match(:name), request)
+      else not_found
+      end
+
+      # Drop the body ourselves: Rails runs Rack::Head above the engine, a bare
+      # Hanami mount has nothing between the router and here.
+      [status, headers, request.head? ? [] : body]
+    end
+
+    private
+
+    def ui(request)
+      return not_found unless OpenapiRuby.configuration.ui_enabled
+
+      html = Serving.swagger_ui_html(
+        schema_urls: schema_urls(request),
+        ui_config: OpenapiRuby.configuration.ui_config
+      )
+      respond(200, "text/html", html)
+    end
+
+    def oauth2_redirect
+      return not_found unless OpenapiRuby.configuration.ui_enabled
+
+      respond(200, "text/html", File.read(Serving.oauth2_redirect_file))
+    end
+
+    def schema_index
+      respond(200, "application/json", {schemas: Serving.schema_names}.to_json)
+    end
+
+    def schema(name, request)
+      document = Serving.schema_document(name.sub(SCHEMA_EXTENSION, ""), request: request)
+      return not_found unless document
+
+      content, content_type = document
+      respond(200, content_type, content)
+    end
+
+    def schema_urls(request)
+      OpenapiRuby.configuration.schemas.map do |name, schema_config|
+        {
+          url: "#{request.script_name}/schemas/#{name}.#{Serving.schema_format}",
+          name: schema_config.dig(:info, :title) || name.to_s
+        }
+      end
+    end
+
+    def respond(status, content_type, body, headers = {})
+      [status, {"content-type" => content_type}.merge(headers), [body]]
+    end
+
+    def not_found
+      respond(404, "application/json", {error: "Not found"}.to_json)
+    end
+
+    def method_not_allowed
+      respond(405, "application/json", {error: "Method not allowed"}.to_json, "allow" => "GET, HEAD")
+    end
+  end
+end

data/lib/openapi_ruby/rake_tasks.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rake"
+require "shellwords"
+require "openapi_ruby/generator/rake_task_support"
+
+module OpenapiRuby
+  # The Rails engine picks up lib/tasks/*.rake on its own; other hosts add
+  #
+  #   require "openapi_ruby/rake_tasks"
+  #
+  # to their Rakefile. Both routes end up here, so the task is defined once.
+  module RakeTasks
+    extend Rake::DSL
+
+    def self.install!
+      return if Rake::Task.task_defined?("openapi_ruby:generate")
+
+      namespace :openapi_ruby do
+        desc "Generate OpenAPI schema files from spec definitions and components"
+        task :generate do
+          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 the host's env defaults to "test" cleanly,
+          # just like rswag did with RSpec::Core::RakeTask.
+          script = support.generate_script(framework, pattern)
+          command = "bundle exec ruby -e #{Shellwords.escape(script)}"
+
+          puts "Generating OpenAPI schemas (#{framework})..."
+          system(support.subprocess_env, command) || abort("Schema generation failed")
+        end
+      end
+    end
+  end
+end
+
+OpenapiRuby::RakeTasks.install!

data/lib/openapi_ruby/serving.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  # Host-neutral logic behind the served schema documents and the Swagger UI.
+  # The Rails controllers and RackApp are both thin shells over this, so the
+  # two hosts cannot drift apart.
+  module Serving
+    module_function
+
+    def schema_names
+      OpenapiRuby.configuration.schemas.keys.map(&:to_s)
+    end
+
+    def schema_config_for(schema_name)
+      OpenapiRuby.configuration.schemas[schema_name.to_sym]
+    end
+
+    def schema_file_path(schema_name)
+      config = OpenapiRuby.configuration
+      ext = (config.schema_output_format == :json) ? "json" : "yaml"
+      File.join(OpenapiRuby.app_root, config.schema_output_dir, "#{schema_name}.#{ext}")
+    end
+
+    def schema_format
+      (OpenapiRuby.configuration.schema_output_format == :json) ? :json : :yaml
+    end
+
+    # Returns [content, content_type], or nil when the schema is unknown or
+    # has not been generated yet — callers turn that into a 404.
+    #
+    # `request` is handed to the configured :openapi_filter untouched. Rails
+    # passes an ActionDispatch::Request and RackApp a Rack::Request; the hook
+    # only ever needs the shared Rack request API.
+    def schema_document(schema_name, request: nil)
+      schema_config = schema_config_for(schema_name)
+      return nil unless schema_config
+
+      file_path = schema_file_path(schema_name)
+      return nil unless File.exist?(file_path)
+
+      content = File.read(file_path)
+
+      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, content_type_for(file_path)]
+    end
+
+    def content_type_for(file_path)
+      file_path.end_with?(".json") ? "application/json" : "application/x-yaml"
+    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
+    end
+
+    def oauth2_redirect_file
+      File.join(gem_root, "app", "views", "openapi_ruby", "oauth2_redirect.html")
+    end
+
+    def gem_root
+      File.expand_path("../..", __dir__)
+    end
+
+    # `schema_urls` is an array of {url:, name:} — the caller builds them,
+    # since only it knows how the docs are mounted.
+    def swagger_ui_html(schema_urls:, ui_config: {})
+      <<~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(schema_urls)},
+              dom_id: '#swagger-ui',
+              deepLinking: true,
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset
+              ],
+              plugins: [
+                SwaggerUIBundle.plugins.DownloadUrl
+              ],
+              layout: "#{(schema_urls.size > 1) ? "StandaloneLayout" : "BaseLayout"}",
+              #{ui_config_js(ui_config)}
+            });
+          </script>
+        </body>
+        </html>
+      HTML
+    end
+
+    def schema_urls_js(schema_urls)
+      if schema_urls.size > 1
+        "urls: #{schema_urls.to_json}"
+      else
+        "url: \"#{schema_urls.first&.fetch(:url)}\""
+      end
+    end
+
+    def ui_config_js(ui_config)
+      ui_config.except(:title).map { |k, v|
+        "#{k}: #{v.to_json}"
+      }.join(",\n          ")
+    end
+  end
+end

data/lib/openapi_ruby/testing/request_builder.rb

@@ -37,7 +37,7 @@ module OpenapiRuby
         result = {}
         query_params.each do |param|
           name = param["name"]
-          result[name] = @param_values[name] if @param_values.key?(name)
+          result[ParameterNames.wire_name(param)] = @param_values[name] if @param_values.key?(name)
         end
         result
       end

data/lib/openapi_ruby/testing/request_validator.rb

@@ -39,19 +39,30 @@ module OpenapiRuby
 
       private
 
+      # A value may arrive under the declared name or the camelized wire name,
+      # depending on whether the caller wrote it or an adapter already renamed
+      # it for the request. Both spellings resolve.
       def extract_param_value(param, params, headers, path_params)
-        name = param["name"]
+        names = ParameterNames.lookup_names(param)
 
         case param["in"]
         when "query"
-          params[name.to_sym] || params[name.to_s]
+          fetch_any(params, names)
         when "path"
-          path_params[name.to_sym] || path_params[name.to_s]
+          fetch_any(path_params, names)
         when "header"
-          headers[name] || headers[name.downcase]
+          fetch_any(headers, names.flat_map { |name| [name, name.downcase] })
         end
       end
 
+      def fetch_any(store, names)
+        names.each do |name|
+          value = store[name.to_sym] || store[name.to_s]
+          return value if value
+        end
+        nil
+      end
+
       def validate_request_body(operation, body)
         errors = []
         rb_spec = operation.request_body_definition

data/lib/openapi_ruby/testing/transport.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Testing
+    # Bridges the adapters onto whichever request-issuing API the host's test
+    # context provides. Rails integration tests take keyword arguments and
+    # expose `response`; rack-test (Hanami, Sinatra, bare Rack) takes
+    # positional arguments plus a Rack env and exposes `last_response`.
+    #
+    # Both response objects answer #status, #body and #headers, so callers
+    # need no further normalisation.
+    module Transport
+      # Rails is checked first: a suite can include Rack::Test::Methods
+      # alongside the integration helpers, and in that case the Rails session
+      # is the one that boots the app under test.
+      def self.for(context)
+        if context.respond_to?(:integration_session)
+          RailsIntegration.new(context)
+        elsif context.respond_to?(:last_response)
+          require_app!(context)
+          RackTest.new(context)
+        elsif OpenapiRuby.rails_host?
+          # A hand-rolled harness that defines the verb methods itself. Left
+          # working rather than second-guessed.
+          RailsIntegration.new(context)
+        else
+          # Without rack-test, dispatch would land on the example-group DSL's
+          # own `get`, and the user would get told that `get` is unavailable
+          # inside an example — true, and no help at all here.
+          raise OpenapiRuby::Error,
+            "openapi_ruby found no way to issue requests from #{describe(context)}. " \
+            "Add rack-test to your bundle, `include Rack::Test::Methods`, and define `app`."
+        end
+      end
+
+      # rack-test resolves `app` lazily, so a missing one surfaces as a bare
+      # NameError from inside the gem rather than as the setup mistake it is.
+      def self.require_app!(context)
+        return if context.respond_to?(:app)
+
+        raise OpenapiRuby::Error,
+          "openapi_ruby needs the Rack app under test in #{describe(context)}. " \
+          "Define it as `let(:app) { MyApp }` in RSpec, or an `app` method in Minitest."
+      end
+
+      def self.describe(context)
+        context.is_a?(Class) ? context.name.to_s : context.class.name.to_s
+      end
+
+      class RailsIntegration
+        def initialize(context)
+          @context = context
+        end
+
+        def dispatch(method, path, params: nil, headers: nil)
+          args = {}
+          args[:params] = params unless params.nil?
+          args[:headers] = headers unless headers.nil?
+          @context.send(method.to_sym, path, **args)
+        end
+
+        def response
+          @context.response
+        end
+      end
+
+      class RackTest
+        # Rack keeps these two out of the HTTP_ namespace.
+        UNPREFIXED_HEADERS = {
+          "content-type" => "CONTENT_TYPE",
+          "content-length" => "CONTENT_LENGTH"
+        }.freeze
+
+        def initialize(context)
+          @context = context
+        end
+
+        # rack-test treats a String `params` as the request body and a Hash as
+        # form/query data, which is the same split the adapters already make.
+        def dispatch(method, path, params: nil, headers: nil)
+          @context.send(method.to_sym, path, params || {}, rack_env(headers || {}))
+        end
+
+        def response
+          @context.last_response
+        end
+
+        private
+
+        def rack_env(headers)
+          headers.each_with_object({}) do |(name, value), env|
+            key = name.to_s
+            env[UNPREFIXED_HEADERS.fetch(key.downcase) { "HTTP_#{key.upcase.tr("-", "_")}" }] = value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openapi_ruby/version.rb

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

data/lib/openapi_ruby.rb

@@ -12,6 +12,7 @@ require "yaml"
 
 require_relative "openapi_ruby/version"
 require_relative "openapi_ruby/errors"
+require_relative "openapi_ruby/host"
 require_relative "openapi_ruby/configuration"
 
 module OpenapiRuby
@@ -53,10 +54,12 @@ require_relative "openapi_ruby/components/key_transformer"
 require_relative "openapi_ruby/components/registry"
 require_relative "openapi_ruby/components/base"
 require_relative "openapi_ruby/components/loader"
+require_relative "openapi_ruby/parameter_names"
 require_relative "openapi_ruby/dsl/response_context"
 require_relative "openapi_ruby/dsl/operation_context"
 require_relative "openapi_ruby/dsl/context"
 require_relative "openapi_ruby/dsl/metadata_store"
+require_relative "openapi_ruby/testing/transport"
 require_relative "openapi_ruby/testing/request_builder"
 require_relative "openapi_ruby/testing/response_validator"
 require_relative "openapi_ruby/testing/request_validator"
@@ -70,6 +73,9 @@ require_relative "openapi_ruby/middleware/error_handler"
 require_relative "openapi_ruby/middleware/schema_resolver"
 require_relative "openapi_ruby/middleware/request_validation"
 require_relative "openapi_ruby/middleware/response_validation"
+require_relative "openapi_ruby/middleware/installer"
+require_relative "openapi_ruby/serving"
+require_relative "openapi_ruby/rack_app"
 require_relative "openapi_ruby/controller_helpers"
 if defined?(Rails::Engine)
   require_relative "openapi_ruby/engine"

data/lib/tasks/openapi_ruby.rake

@@ -1,21 +1,3 @@
 # 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
-    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 = 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
+require "openapi_ruby/rake_tasks"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Morten Hartvig
@@ -51,23 +51,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: railties
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
-description: 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.
+description: A unified OpenAPI toolkit for Rails and Hanami 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.
 email:
 - morten@hartvigsen.dev
 executables: []
@@ -110,19 +96,27 @@ files:
 - lib/openapi_ruby/generator/rake_task_support.rb
 - lib/openapi_ruby/generator/schema_writer.rb
 - lib/openapi_ruby/generator/test_schema_suppressor.rb
+- lib/openapi_ruby/hanami.rb
+- lib/openapi_ruby/host.rb
 - lib/openapi_ruby/middleware/coercion.rb
 - lib/openapi_ruby/middleware/error_handler.rb
+- lib/openapi_ruby/middleware/installer.rb
 - lib/openapi_ruby/middleware/path_matcher.rb
 - lib/openapi_ruby/middleware/request_validation.rb
 - lib/openapi_ruby/middleware/response_validation.rb
 - lib/openapi_ruby/middleware/schema_resolver.rb
 - lib/openapi_ruby/minitest.rb
+- lib/openapi_ruby/parameter_names.rb
+- lib/openapi_ruby/rack_app.rb
+- lib/openapi_ruby/rake_tasks.rb
 - lib/openapi_ruby/rspec.rb
+- lib/openapi_ruby/serving.rb
 - lib/openapi_ruby/testing/assertions.rb
 - lib/openapi_ruby/testing/coverage.rb
 - lib/openapi_ruby/testing/request_builder.rb
 - lib/openapi_ruby/testing/request_validator.rb
 - lib/openapi_ruby/testing/response_validator.rb
+- lib/openapi_ruby/testing/transport.rb
 - lib/openapi_ruby/version.rb
 - lib/tasks/openapi_ruby.rake
 homepage: https://github.com/openapi-ruby/openapi-ruby
@@ -149,6 +143,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: OpenAPI 3.0/3.1 toolkit for Rails — spec generation, schema components, and
-  runtime validation
+summary: OpenAPI 3.0/3.1 toolkit for Rails and Hanami — spec generation, schema components,
+  and runtime validation
 test_files: []