grape-oas 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 585f37dd85b6630ef0d9599e3c1a02172cda35ff81ba6b9782e500d6bdaf8115
-  data.tar.gz: b7e2cec6f5c24f7927e7290c87dffd2a488fe77768c039d9bc711cc79e868373
+  metadata.gz: e76945cff9198556752b881ff62da8c288a18e3f6447a36b7668d516ed575f4f
+  data.tar.gz: 8f36610d66d2d5935004972fdc063e74316b2a576be030ce7d8a0a903fa43f79
 SHA512:
-  metadata.gz: 74106be01a4e9d0a9625d4b328df7b319de5dfe1da3d74d37f605d9328eb7fe200dccc761a865a66963797ad209871f71402f0c601e7f9d27ef9fbfe23408c69
-  data.tar.gz: fbc867bb5e8167fe096a6024285986ac410385b3bc07cdca2b1c62c73bb0cbd7a4e9e1f0dff271212637dac1ac43842e8417d36b93bc39984d396cc8cd9329f3
+  metadata.gz: df261c7d71e8c228c096484cda70c821e4cdd58f1aad04b31bf402513dd414eff69512a38d9c6ef131de418fd19403c0ddadfc4ae7fe0bd8e12078ffc66e285a
+  data.tar.gz: 233f3e233f053f12f7b9fb2eb4635c8969233b4d8848b61048bf273512cffed54ce9499f473b90b56875c0d429f4d12a46f74148689fa122002a7e049fc1f383

data/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-09-07
+
+### Added
+
+- [#123](https://github.com/numbata/grape-oas/pull/123): Add opt-in OAS2 composition extensions and include missing referenced alternatives in definitions - [@numbata](https://github.com/numbata).
+- [#96](https://github.com/numbata/grape-oas/pull/96): Pin rubocop versions and add performance/packaging/rake plugins - [@numbata](https://github.com/numbata).
+- [#92](https://github.com/numbata/grape-oas/pull/92): Add cross-tool AI-agent contributor guidance and tighten gem file packaging - [@numbata](https://github.com/numbata).
+- [#88](https://github.com/numbata/grape-oas/pull/88): Add configurable `GrapeOAS.schema_ref_name` callable that controls how a schema's canonical class name is mangled into its OAS component/definition ref name. Default behavior (`name.gsub("::", "_")`) is byte-identical to prior output; applies uniformly across OAS 2.0 and OAS 3 ref emission paths - [@abeljim8am](https://github.com/abeljim8am).
+
+### Fixed
+
+- [#128](https://github.com/numbata/grape-oas/pull/128): Honor string keys in entity-root documentation - [@numbata](https://github.com/numbata).
+- [#127](https://github.com/numbata/grape-oas/pull/127): Drop stale OAS2 `x-anyOf`/`x-oneOf` compatibility extensions when native OAS3 composition is present - [@numbata](https://github.com/numbata).
+- [#126](https://github.com/numbata/grape-oas/pull/126): Prefer bare `$ref` in nullable OAS3 null-union alternatives (drop redundant single-element `allOf`) - [@numbata](https://github.com/numbata).
+- [#125](https://github.com/numbata/grape-oas/pull/125): Preserve nullability on root OAS3 request and response `$ref` schemas - [@numbata](https://github.com/numbata).
+- [#122](https://github.com/numbata/grape-oas/pull/122): Treat params declared inside Grape `given` blocks as optional — no longer emitted as unconditionally required - [@numbata](https://github.com/numbata).
+- [#121](https://github.com/numbata/grape-oas/pull/121): Preserve nullable references, array items, and polymorphic discriminators in OAS 3.0/3.1 - [@numbata](https://github.com/numbata).
+- [#120](https://github.com/numbata/grape-oas/pull/120): Honor explicit route `consumes:`/`produces:` independently so form request bodies are documented with the declared media type - [@numbata](https://github.com/numbata).
+- [#119](https://github.com/numbata/grape-oas/pull/119): Stop inferring `format: int32` for generic `Integer`/`"integer"` declarations; explicit int32/int64 widths are still preserved - [@numbata](https://github.com/numbata).
+- [#113](https://github.com/numbata/grape-oas/pull/113): Use OAS 3.1 schema rendering for inline parameters, request bodies, and responses - [@numbata](https://github.com/numbata).
+- [#112](https://github.com/numbata/grape-oas/pull/112): Exclude format extensions from path parameter discovery - [@numbata](https://github.com/numbata).
+- [#100](https://github.com/numbata/grape-oas/pull/100): Preserve nil enum members when the selected nullable strategy can express them - [@numbata](https://github.com/numbata).
+- [#104](https://github.com/numbata/grape-oas/pull/104): Preserve array-valued schema examples and Boolean false examples from parameter/entity documentation in OAS 3.0/3.1; omit incompatible scalar examples - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#109](https://github.com/numbata/grape-oas/pull/109): Fix Grape 3.3 variant collections, Grape 4.0 route metadata, and OAS 2.0 query array items - [@numbata](https://github.com/numbata).
+- [#97](https://github.com/numbata/grape-oas/pull/97): Default OAS 2.0 nullable strategy to EXTENSION so nullable fields emit `x-nullable: true` without explicit opt-in - [@numbata](https://github.com/numbata).
+- [#79](https://github.com/numbata/grape-oas/pull/79): Fix docs: `nickname` is supported in grape-oas - [@bogdan](https://github.com/bogdan).
+- [#78](https://github.com/numbata/grape-oas/pull/78): Fix: use empty schema for undocumented responses instead of `{ type: string }` - [@bogdan](https://github.com/bogdan).
+- [#74](https://github.com/numbata/grape-oas/pull/74): Fix BigDecimal range bounds serializing as JSON strings - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#76](https://github.com/numbata/grape-oas/pull/76): Emit OAS-version-correct schema for file types - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#82](https://github.com/numbata/grape-oas/pull/82): Fix: respect `documentation: { hidden: true }` on entity exposures - [@bogdan](https://github.com/bogdan).
+- [#80](https://github.com/numbata/grape-oas/pull/80): Fix: hide documentation routes from generated spec by default - [@bogdan](https://github.com/bogdan).
+- [#98](https://github.com/numbata/grape-oas/pull/98): Honor `documentation: { x: { nullable: true } }` on entity exposures - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#85](https://github.com/numbata/grape-oas/pull/85): Honor `is_array: true` on the plain-entity response branch - [@abeljim8am](https://github.com/abeljim8am).
+- [#87](https://github.com/numbata/grape-oas/pull/87): Fix `SchemaIndexer#index_schema` to recurse into `schema.items` so entities reachable only through an array wrapper (e.g. a property declared as `Array<OtherEntity>`) are included in the indexed schemas set - [@abeljim8am](https://github.com/abeljim8am).
+- [#102](https://github.com/numbata/grape-oas/pull/102): Fix: nullable entity ref must not mutate shared cached schema - [@bogdan](https://github.com/bogdan).
+- [#105](https://github.com/numbata/grape-oas/pull/105): Place array-valued `example` on the array schema instead of `items` for entity `is_array:` exposures without mutating shared entity schemas - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#86](https://github.com/numbata/grape-oas/pull/86): Omit response content for bodyless HTTP statuses (`1xx`, `204`, `205`, `304`), including declared entities and examples, so generated OpenAPI responses remain valid - [@abeljim8am](https://github.com/abeljim8am).
+- [#84](https://github.com/numbata/grape-oas/pull/84): Substitute the concrete path version into route templates, including prefixed and mounted routes, for `version "...", using: :path` while preserving user-defined version parameters with other versioning strategies - [@abeljim8am](https://github.com/abeljim8am).
+
+### Changed
+
+- [#95](https://github.com/numbata/grape-oas/pull/95): Entity exposures now consult `GrapeOAS.type_resolvers` - [@numbata](https://github.com/numbata).
+
 ## [1.4.0] - 2026-04-23
 
 ### Fixed

data/README.md

@@ -36,15 +36,17 @@ Grape::OAS is built around a **DTO (Data Transfer Object) architecture** that se
 ## Features
 
 - **Multi-version support**: Generate OAS 2.0, 3.0, or 3.1 from the same API
-- **Entity integration**: Works with [grape-entity](https://github.com/ruby-grape/grape-entity) and [dry-struct](https://dry-rb.org/gems/dry-struct/)
+- **Entity and contract integration**: Works with [grape-entity](https://github.com/ruby-grape/grape-entity), [dry-validation](https://dry-rb.org/gems/dry-validation/), and [dry-schema](https://dry-rb.org/gems/dry-schema/)
 - **Automatic type inference**: Derives OpenAPI types from Grape parameter definitions
 - **Flexible output**: Mount as an endpoint or generate programmatically
 
 ## Compatibility
 
-| grape-oas | grape | grape-entity | dry-struct | Ruby |
-|-----------|-------|--------------|------------|------|
-| 0.1.x | >= 3.0 | >= 0.7 | >= 1.0 | >= 3.2 |
+| grape-oas | grape | Ruby |
+|-----------|-------|------|
+| 1.5.x | >= 3.0 | >= 3.2 |
+
+Entity and contract integrations are optional; install the gems your API uses.
 
 ## Installation
 
@@ -52,11 +54,12 @@ Grape::OAS is built around a **DTO (Data Transfer Object) architecture** that se
 gem 'grape-oas'
 ```
 
-For entity support:
+For entity or contract support, add the relevant gems:
 
 ```ruby
-gem 'grape-entity'  # For grape-entity support
-gem 'dry-struct'    # For dry-struct contract support
+gem 'grape-entity'    # Grape::Entity response schemas
+gem 'dry-validation'  # Dry::Validation::Contract request schemas
+gem 'dry-schema'      # Standalone Dry::Schema request schemas
 ```
 
 ## Quick Start
@@ -82,10 +85,15 @@ end
 ```
 
 Documentation available at:
+
 - `/swagger_doc` - OpenAPI 3.0 (default)
 - `/swagger_doc?oas=2` - OpenAPI 2.0
 - `/swagger_doc?oas=3.1` - OpenAPI 3.1
 
+Documentation routes are accessible over HTTP but excluded from the generated
+specification by default. Set `hide_documentation_path: false` to include them.
+To disable the endpoints, omit or conditionally call `add_oas_documentation`.
+
 ### Manual Generation
 
 ```ruby
@@ -96,17 +104,26 @@ puts JSON.pretty_generate(spec)
 
 ### Rake Tasks
 
+Load your API before registering the tasks:
+
 ```ruby
 # In Rakefile
-require 'grape_oas/tasks'
+require 'grape_oas'
+require 'grape_oas/rake/oas_tasks'
+require_relative 'app/api' # Defines MyAPI; adjust to your application's path
+
+GrapeOAS::Rake::OasTasks.new(MyAPI)
 ```
 
 ```bash
-rake grape_oas:generate[MyAPI,oas31,spec/openapi.json]
+mkdir -p spec
+bundle exec rake oas:generate version=oas31 output=spec/openapi.json
 ```
 
 ## Documentation
 
+Upgrading an existing application? Read [UPGRADING.md](UPGRADING.md).
+
 | Document | Description |
 |----------|-------------|
 | [Configuration](docs/CONFIGURATION.md) | All configuration options |
@@ -202,7 +219,7 @@ schema = GrapeOAS.generate(app: API, schema_type: :custom)
 git clone https://github.com/numbata/grape-oas.git
 cd grape-oas
 bin/setup
-bundle exec rake test
+bundle exec rake
 ```
 
 ## Contributing

data/UPGRADING.md

@@ -0,0 +1,104 @@
+# Upgrading grape-oas
+
+### Upgrading to >= 1.5.0
+
+When upgrading from 1.4.0, regenerate your OpenAPI documents and review the diff before regenerating clients.
+This release corrects several schema shapes and changes how documentation routes
+are mounted. See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
+
+#### Documentation routes are mounted even when hidden
+
+`hide_documentation_path: true` previously prevented documentation routes from
+being mounted. It now mounts them and hides them from the generated specification.
+It is also the new default.
+
+If you used this option to disable documentation in an environment, conditionally
+omit the DSL call instead:
+
+```ruby
+class API < Grape::API
+  # Declare your API routes here.
+
+  add_oas_documentation if ENV["ENABLE_API_DOCS"] == "true"
+end
+```
+
+To include the documentation routes in the generated specification, use
+`add_oas_documentation(hide_documentation_path: false)`. Hiding a route from the
+specification does not restrict HTTP access to it.
+
+#### Generic integers no longer imply a 32-bit format
+
+Generic `Integer` and `"integer"` declarations now emit `type: integer` without
+the previously inferred `format: int32`. This can change the integer type selected
+by a client generator. Declare a width explicitly when your API requires it:
+
+```ruby
+params do
+  requires :count, type: Integer, documentation: { format: "int32" }
+end
+```
+
+For entity exposures, use
+`documentation: { type: "integer", format: "int64" }` (or `"int32"`).
+
+#### Entity exposures use the type resolver registry
+
+Entity exposures now consult `GrapeOAS.type_resolvers`. Existing custom resolvers
+can therefore affect response schemas as well as request parameters. Review their
+`handles?` predicates and compare generated entity schemas after upgrading.
+
+The registry also has migration-relevant changes:
+
+- Replace registry calls to `handles?(type)` with
+  `registered_resolver_for?(type)`; `handles?` now emits a deprecation warning.
+  Custom resolver classes still implement their own `handles?` method.
+- `build_schema(type)` now returns a fallback string schema when no registered
+  resolver supplies a schema, including after `clear`. Do not use a `nil` result
+  to detect unsupported types. `registered_resolver_for?` checks whether a
+  registered resolver claims the type; it does not guarantee that the resolver
+  will return a schema.
+- A resolver returning `nil` from `build_schema` now lets the registry try later
+  resolvers before using the fallback.
+- `find` is now private. Use `registered_resolver_for?` for a membership check or
+  `build_schema` to resolve a type. To inspect the first matching resolver, use
+  `GrapeOAS.type_resolvers.to_a.find { |resolver| resolver.handles?(type) }`.
+
+#### Explicit media types affect OAS2 form generation
+
+Route `consumes:` and `produces:` declarations now override inferred media types
+independently. Check existing declarations for stale values.
+
+For OAS2 operations consuming only `application/x-www-form-urlencoded` or
+`multipart/form-data`, request properties now become `formData` parameters.
+Complex form fields (objects, compositions, or referenced array items) raise
+`ArgumentError` during generation. Use OAS3 to describe those requests, or simplify
+the form schema if that accurately reflects your API. Primitive fields, files,
+and arrays of primitives remain supported.
+
+#### Generated schemas reflect corrected types and requiredness
+
+Review schema snapshots and generated clients for these corrections:
+
+- **Nullability:** OAS2 emits `x-nullable: true` by default for nullable schemas.
+  OAS3.1 inline parameters, request bodies, and responses now use its JSON Schema
+  null representation. Nullable OAS3 references and compositions retain
+  nullability, and null-union alternatives may now contain a bare `$ref` instead
+  of a single-element `allOf`. Update tooling that assumes the old wrapper shape.
+- **Conditional parameters:** fields declared inside Grape `given` blocks are
+  optional in the generated schema unless also required unconditionally.
+  Conditional fields alone no longer make the request body required. Grape still
+  enforces conditions at runtime; the generated schema does not encode them.
+- **Responses:** undocumented response schemas are now empty (`{}`) instead of
+  `type: string`. Declare a response entity if consumers need a concrete type.
+  Responses with status `1xx`, `204`, `205`, or `304` omit body schemas/content,
+  including declared entities and examples. Plain-entity responses with
+  `is_array: true` now correctly emit arrays.
+- **Hidden entity fields:** exposures with `documentation: { hidden: true }` are
+  omitted. Remove that flag if the field should remain documented.
+- **Versioned paths:** path-based Grape versions now appear as concrete path
+  segments instead of unresolved version parameters. Regenerate clients that
+  previously accepted the version as an argument.
+
+New `schema_ref_name` and `oas2_composition_extensions` options are opt-in and
+require no configuration changes for existing applications.

data/grape-oas.gemspec

@@ -24,7 +24,8 @@ Gem::Specification.new do |spec|
     "rubygems_mfa_required" => "true"
   }
 
-  spec.files = Dir["lib/**/*", "*.md", "LICENSE.txt", "grape-oas.gemspec"]
+  spec.files = Dir["lib/**/*"].reject { |path| File.directory?(path) } +
+               %w[README.md CHANGELOG.md UPGRADING.md LICENSE.txt grape-oas.gemspec]
 
   spec.add_dependency "grape", ">= 3.0"
   spec.add_dependency "zeitwerk"

data/lib/grape_oas/api_model/api.rb

@@ -11,7 +11,7 @@ module GrapeOAS
     class API < Node
       attr_accessor :title, :version, :paths, :servers, :tag_defs, :components,
                     :host, :base_path, :schemes, :security_definitions, :security,
-                    :registered_schemas, :suppress_default_error_response, :nullable_strategy
+                    :registered_schemas, :suppress_default_error_response, :nullable_strategy, :oas2_composition_extensions
 
       def initialize(title:, version:)
         super()
@@ -29,6 +29,7 @@ module GrapeOAS
         @registered_schemas = []
         @suppress_default_error_response = false
         @nullable_strategy = nil
+        @oas2_composition_extensions = false
       end
 
       def add_path(path)

data/lib/grape_oas/api_model/schema.rb

@@ -14,7 +14,7 @@ module GrapeOAS
         examples default extensions
         min_length max_length pattern
         minimum maximum exclusive_minimum exclusive_maximum
-        min_items max_items
+        min_items max_items unique_items
         discriminator all_of one_of any_of
       ].freeze
 

data/lib/grape_oas/api_model_builder.rb

@@ -20,6 +20,7 @@ module GrapeOAS
       @api.registered_schemas = build_registered_schemas(options[:models])
       @api.suppress_default_error_response = options[:suppress_default_error_response] || false
       @api.nullable_strategy = options[:nullable_strategy]
+      @api.oas2_composition_extensions = options[:oas2_composition_extensions] == true
 
       @namespace_filter = options[:namespace]
       @apis = []
@@ -53,12 +54,12 @@ module GrapeOAS
     def build_registered_schemas(models)
       return [] unless models
 
-      Array(models).map do |model|
+      Array(models).filter_map do |model|
         model = model.constantize if model.is_a?(String)
         GrapeOAS.introspectors.build_schema(model, stack: [], registry: {})
       rescue StandardError
         nil
-      end.compact
+      end
     end
   end
 end

data/lib/grape_oas/api_model_builders/concerns/content_type_resolver.rb

@@ -8,6 +8,14 @@ module GrapeOAS
       module ContentTypeResolver
         private
 
+        def explicit_media_types(key)
+          declared = route.options[key] || route.options.dig(:documentation, key)
+          mimes = Array(declared).filter_map do |mime|
+            mime.to_s.include?("/") ? mime.to_s : Grape::ContentTypes.content_types_for(nil)[mime.to_s.to_sym]
+          end
+          mimes.empty? ? nil : mimes.uniq
+        end
+
         def resolve_content_types
           default_format = route_default_format_from_route || default_format_from_app_or_api
           content_types = route_content_types_from_route
@@ -24,7 +32,7 @@ module GrapeOAS
 
           mimes << mime_for_format(default_format) if mimes.empty? && default_format
 
-          mimes = mimes.map { |m| normalize_mime(m) }.compact
+          mimes = mimes.filter_map { |m| normalize_mime(m) }
           mimes.empty? ? [Constants::MimeTypes::JSON] : mimes.uniq
         end
 

data/lib/grape_oas/api_model_builders/concerns/oas_utilities.rb

@@ -24,6 +24,19 @@ module GrapeOAS
           OasUtilities.extract_extensions(hash)
         end
 
+        # Extracts nullable flag from a documentation hash.
+        #
+        # @param doc [Hash] the documentation hash
+        # @return [Boolean] true if nullable
+        def self.extract_nullable(doc)
+          doc[:nullable] || (doc[:x].is_a?(Hash) && doc[:x][:nullable]) || false
+        end
+
+        # Instance method version
+        def extract_nullable(doc)
+          OasUtilities.extract_nullable(doc)
+        end
+
         # Converts a CamelCase string to snake_case.
         #
         # @param str [String] the string to convert

data/lib/grape_oas/api_model_builders/concerns/route_validations.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module Concerns
+      module RouteValidations
+        private
+
+        # Grape 3.x snapshots validators on `inheritable_setting.route[:saved_validations]`.
+        # Grape 4.0 renamed that to `#route_validations` / `route[:validations]` (grape#2811).
+        def grape_route_validations(setting)
+          if setting.respond_to?(:route_validations)
+            validations = setting.route_validations
+            return validations if validations.is_a?(Array)
+          end
+          return unless setting.respond_to?(:route)
+
+          route_store = setting.route
+          return unless route_store.is_a?(Hash)
+
+          route_store[:saved_validations] || route_store[:validations]
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/concerns/type_resolver.rb

@@ -14,6 +14,7 @@ module GrapeOAS
       module TypeResolver
         TYPED_ARRAY_PATTERN = Constants::TypePatterns::TYPED_ARRAY
         MULTI_TYPE_PATTERN = Constants::TypePatterns::MULTI_TYPE
+        VARIANT_COLLECTION_PATTERN = Constants::TypePatterns::VARIANT_COLLECTION
 
         # Resolves a Ruby class or type name to its OpenAPI schema type string.
         # Handles both Ruby classes (Integer, Float) and string type names ("integer", "float").
@@ -39,8 +40,9 @@ module GrapeOAS
 
           type_str = type.to_s
 
-          # Handle Grape's typed array notation like "[String]"
-          return Constants::SchemaTypes::ARRAY if type_str.match?(TYPED_ARRAY_PATTERN)
+          # Handle Grape's typed array notation like "[String]" / "Array[String]"
+          # and Grape 3.3+ variant collections like "Array[Integer, String]".
+          return Constants::SchemaTypes::ARRAY if type_str.match?(TYPED_ARRAY_PATTERN) || type_str.match?(VARIANT_COLLECTION_PATTERN)
 
           # Handle string/symbol type names
           Constants.primitive_type(type_str) || Constants::SchemaTypes::STRING

data/lib/grape_oas/api_model_builders/operation.rb

@@ -49,8 +49,7 @@ module GrapeOAS
           slug = route
                  .pattern
                  .origin
-                 .gsub(/[^a-z0-9]+/i, "_")
-                 .gsub(/_+/, "_")
+                 .gsub(/[^a-z0-9]+/i, "_").squeeze("_")
                  .sub(/^_|_$/, "")
 
           "#{http_method}_#{slug}"
@@ -125,11 +124,11 @@ module GrapeOAS
       end
 
       def consumes
-        resolve_content_types
+        explicit_media_types(:consumes) || resolve_content_types
       end
 
       def produces
-        resolve_content_types
+        explicit_media_types(:produces) || resolve_content_types
       end
 
       def operation_extensions

data/lib/grape_oas/api_model_builders/path.rb

@@ -10,6 +10,11 @@ module GrapeOAS
       PATH_PARAMETER_PATTERN = %r{(?<=/):(?<param>[^/]+)}
       private_constant :PATH_PARAMETER_PATTERN
 
+      # Matches Grape's wildcard segments: /?*param or /*param
+      # The optional ? before * is Grape's syntax for an optional leading slash
+      WILDCARD_PARAMETER_PATTERN = %r{\??\*(?<param>[^/()]+)}
+      private_constant :WILDCARD_PARAMETER_PATTERN
+
       NORMALIZED_PLACEHOLDER = /\{[^}]+\}/
       private_constant :NORMALIZED_PLACEHOLDER
 
@@ -28,7 +33,7 @@ module GrapeOAS
         @routes.each_with_object({}) do |route, api_routes|
           next if skip_route?(route)
 
-          route_path = sanitize_path(route.path)
+          route_path = sanitize_path(route.path, route: route)
           normalized = normalize_template(route_path)
 
           canonical_info = canonical_paths[normalized]
@@ -79,7 +84,7 @@ module GrapeOAS
       def filtered_by_namespace?(route)
         return false unless namespace_filter
 
-        route_path = sanitize_path(route.path)
+        route_path = sanitize_path(route.path, route: route)
         namespace_prefix = namespace_filter.start_with?("/") ? namespace_filter : "/#{namespace_filter}"
 
         # Match exact namespace or namespace followed by / or {
@@ -95,10 +100,32 @@ module GrapeOAS
           .build
       end
 
-      def sanitize_path(path)
-        path
-          .gsub(EXTENSION_PATTERN, "") # Remove format extensions like (.json)
-          .gsub(PATH_PARAMETER_PATTERN, "{\\k<param>}") # Replace named parameters with curly braces
+      def sanitize_path(path, route: nil)
+        sanitized = path.gsub(EXTENSION_PATTERN, "") # Remove format extensions like (.json)
+                        .gsub(WILDCARD_PARAMETER_PATTERN, "{\\k<param>}") # Replace *param / /?*param with {param}
+                        .gsub(PATH_PARAMETER_PATTERN, "{\\k<param>}") # Replace :param with {param}
+
+        concrete_version = concrete_path_version(route) if route
+        return sanitized unless concrete_version
+
+        # Path versioning owns {version}; Grape rejects duplicate capture names.
+        sanitized.sub("{version}", concrete_version)
+      end
+
+      def concrete_path_version(route)
+        setting = route.app.inheritable_setting
+        version_options = if setting.respond_to?(:version_options)
+                            setting.version_options
+                          else
+                            setting.namespace_inheritable[:version_options]
+                          end
+        return nil unless version_options&.to_h&.dig(:using) == :path
+
+        values = Array(route.version)
+        return nil unless values.length == 1
+
+        value = values.first.to_s
+        value.empty? ? nil : value
       end
 
       def normalize_template(path)

data/lib/grape_oas/api_model_builders/request.rb

@@ -3,6 +3,7 @@
 module GrapeOAS
   module ApiModelBuilders
     class Request
+      include Concerns::RouteValidations
       include Concerns::TypeResolver
       include Concerns::OasUtilities
 
@@ -96,7 +97,9 @@ module GrapeOAS
 
       # Find contract from Grape's contract storage locations.
       # Contracts can be defined in several ways:
-      # 1. Via `contract MyContract` DSL - stores in inheritable_setting.route[:saved_validations]
+      # 1. Via `contract MyContract` DSL - stored on the endpoint's inheritable
+      #    settings (`route_validations` on Grape 4.0, `route[:saved_validations]`
+      #    on Grape 3.x)
       # 2. Via `desc "...", contract: MyContract` - stores in route.options[:contract]
       # 3. Via `desc "...", schema: MySchema` - stores in route.options[:schema]
       # 4. Via route.settings[:contract] - used by mounted APIs or legacy configuration
@@ -116,22 +119,15 @@ module GrapeOAS
       end
 
       # Extract contract from Grape's native contract() DSL storage location.
-      # When using `contract MyContract` in Grape DSL, the contract is stored in
-      # route.app.inheritable_setting.route[:saved_validations] as validator options.
-      # This is a point-in-time copy specific to this endpoint, ensuring each route
+      # When using `contract MyContract` in Grape DSL, the contract is stored as
+      # a point-in-time copy specific to this endpoint, ensuring each route
       # gets only its own contract even when multiple routes define different contracts.
       #
       # @return [Object, nil] The contract instance or nil if not found
       def extract_contract_from_grape_validations
         return unless route.respond_to?(:app) && route.app.respond_to?(:inheritable_setting)
 
-        setting = route.app.inheritable_setting
-        return unless setting.respond_to?(:route)
-
-        # Use route[:saved_validations] which contains only the validations
-        # for this specific endpoint (point-in-time copy), not the shared
-        # namespace_stackable[:validations] which contains all validators for the API class
-        validations = setting.route[:saved_validations]
+        validations = grape_route_validations(route.app.inheritable_setting)
         return unless validations.is_a?(Array)
 
         # Find ContractScopeValidator which holds the Dry contract/schema.
@@ -147,10 +143,7 @@ module GrapeOAS
 
             return v.dig(:opts, :schema)
           when Grape::Validations::Validators::ContractScopeValidator
-            # Grape 3.2 removed attr_reader :schema and freezes the validator,
-            # so instance_variable_get is the only way to access the schema.
-            # TODO: use v.schema once ruby-grape/grape#2657 restores the accessor.
-            schema = v.instance_variable_get(:@schema)
+            schema = contract_schema_from(v)
             GrapeOAS.logger&.warn("ContractScopeValidator found but @schema is nil") if schema.nil?
             return schema
           end
@@ -159,6 +152,11 @@ module GrapeOAS
         nil
       end
 
+      def contract_schema_from(validator)
+        schema = validator.schema if validator.respond_to?(:schema)
+        schema || validator.instance_variable_get(:@schema)
+      end
+
       def build_contract_schema
         contract = find_contract
         return unless contract
@@ -265,7 +263,7 @@ module GrapeOAS
       end
 
       def path_param_names
-        names = route.path.scan(RequestParams::ROUTE_PARAM_REGEX)
+        names = RequestParams.path_param_names(route.path)
         mapped_names = path_param_name_map ? path_param_name_map.values : []
         (names + mapped_names).map(&:to_s).uniq
       end