grape-oas 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f97a967ef31212399ee7765f184a358e755b4364578cbc43d3fdaf75a919638
-  data.tar.gz: c56afb98329feaa1227d6ee252cbf5866ddc0144eac15dc6db8e34f9718d4731
+  metadata.gz: 585f37dd85b6630ef0d9599e3c1a02172cda35ff81ba6b9782e500d6bdaf8115
+  data.tar.gz: b7e2cec6f5c24f7927e7290c87dffd2a488fe77768c039d9bc711cc79e868373
 SHA512:
-  metadata.gz: efed55aaa9f34d9045e495b2c8cbccea7b4da8381b4d2c58628e20785947319f42cc3a1e9952bac87219cb290cdbb81ac31bca7107acc3be3db13e027087c1ac
-  data.tar.gz: aa0eebcf7dd0b7122346150adfdf6e5dbfc8ed0287470ecedfe18ff9a95afca3376479899e0dc1e6298be3e65da3711238988b329839b4af68d48dd622bcd1f0
+  metadata.gz: 74106be01a4e9d0a9625d4b328df7b319de5dfe1da3d74d37f605d9328eb7fe200dccc761a865a66963797ad209871f71402f0c601e7f9d27ef9fbfe23408c69
+  data.tar.gz: fbc867bb5e8167fe096a6024285986ac410385b3bc07cdca2b1c62c73bb0cbd7a4e9e1f0dff271212637dac1ac43842e8417d36b93bc39984d396cc8cd9329f3

data/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.4.0] - 2026-04-23
+
+### Fixed
+
+- [#60](https://github.com/numbata/grape-oas/pull/60): Fix `Dangerfile` to properly look for tests - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#58](https://github.com/numbata/grape-oas/pull/58): Fix contract extraction compatibility with Grape 3.2 - [@numbata](https://github.com/numbata).
+- [#57](https://github.com/numbata/grape-oas/pull/57): Fix `Array<Array<...>>` double-wrap when `is_array: true` is used with typed array notation like `type: [String]` — the redundant `is_array` flag no longer produces a nested array schema - [@numbata](https://github.com/numbata).
+- [#59](https://github.com/numbata/grape-oas/pull/59): Export `default` param values to OAS2 and OAS3 output - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#61](https://github.com/numbata/grape-oas/pull/61): Respect `entity_name` on `grape::entity` subclasses - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#68](https://github.com/numbata/grape-oas/pull/68): De-duplicate parameter `description` between the Parameter Object and its nested `schema` in OAS 3 output - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#70](https://github.com/numbata/grape-oas/pull/70): Propagate schema attributes (`default`, `enum`, constraints, extensions) through `$ref` and composition paths - [@numbata](https://github.com/numbata).
+
+### Changed
+
+- [#64](https://github.com/numbata/grape-oas/pull/64): Memoize content-type and default-format resolution per generation — eliminates redundant calls that scaled with route × response count - [@JuniorJoanis](https://github.com/JuniorJoanis).
+- [#62](https://github.com/numbata/grape-oas/pull/62): Default to body params for post/put/patch routes - [@olivier-thatch](https://github.com/olivier-thatch).
+
+## [1.3.0] - 2026-03-27
+
+### Added
+
+- [#48](https://github.com/numbata/grape-oas/pull/48): Add configurable `GrapeOAS.logger` for schema generation warnings - [@numbata](https://github.com/numbata).
+- [#43](https://github.com/numbata/grape-oas/pull/43): Bump actions/upload-artifact from 6 to 7 - [@dependabot[bot]](https://github.com/dependabot[bot]).
+- [#51](https://github.com/numbata/grape-oas/pull/51): Add inline nesting exposure support — block-based `expose :key do ... end` now produces inline object schemas with preserved enum values, min/max constraints, and metadata - [@numbata](https://github.com/numbata).
+
+### Changed
+
+- [#52](https://github.com/numbata/grape-oas/pull/52): Extract `SchemaConstraints` — centralizes numeric/string constraint application (min/max, exclusive flags, length, pattern) and adds `exclusive_minimum`/`exclusive_maximum` support - [@numbata](https://github.com/numbata).
+- [#50](https://github.com/numbata/grape-oas/pull/50): Extract `ValuesNormalizer` — consolidates Proc/Set/Hash value normalization into a single module used by both request params and entity exposures - [@numbata](https://github.com/numbata).
+
+### Fixed
+
+- [#55](https://github.com/numbata/grape-oas/pull/55): Preserve enum values on cached entity schemas — dup the shared schema before applying enum instead of silently discarding the constraint; emit a warning naming the entity - [@numbata](https://github.com/numbata).
+- [#56](https://github.com/numbata/grape-oas/pull/56): Make `NestingMerger` depth-cap warning actionable — include property name and depth cap value in the message - [@numbata](https://github.com/numbata).
+- [#50](https://github.com/numbata/grape-oas/pull/50): Fix `[false]` enum silently dropped — `[false].any?` returns `false` in Ruby, causing boolean-only enum constraints to be discarded - [@numbata](https://github.com/numbata).
+
+- [#49](https://github.com/numbata/grape-oas/pull/49): Fix OOM on wide string range expansion in `values:` — replace unbounded `range.to_a` with bounded enumeration; non-numeric ranges on numeric schemas and numeric ranges on non-numeric schemas now warn and are ignored instead of silently producing invalid output - [@numbata](https://github.com/numbata).
+- [#46](https://github.com/numbata/grape-oas/pull/46): Fix `is_array: true` in request param documentation being ignored for primitive types — only entity types were wrapped in array schema - [@numbata](https://github.com/numbata).
+- [#42](https://github.com/numbata/grape-oas/pull/42): Fix array items `description` and `nullable` placement — hoist to outer array schema instead of wrapping `items` in `allOf`; fix `:description` field naming collision in `PropertyExtractor` - [@numbata](https://github.com/numbata).
+- [#44](https://github.com/numbata/grape-oas/pull/44): Fix RuboCop 1.85 offenses - [@numbata](https://github.com/numbata).
+- [#47](https://github.com/numbata/grape-oas/pull/47): Fix duplicate entries in `Schema#required` array when the same property is added multiple times with `required: true` - [@numbata](https://github.com/numbata).
+
 ## [1.2.0] - 2026-03-02
 
 ### Added

data/README.md

@@ -150,6 +150,12 @@ class Entity::User < Grape::Entity
   expose :id, documentation: { type: Integer }
   expose :name, documentation: { type: String }
   expose :posts, using: Entity::Post, documentation: { is_array: true }
+
+  # Block-based nesting produces an inline object schema
+  expose :meta do
+    expose :role, documentation: { type: String, values: %w[admin user guest] }
+    expose :verified, documentation: { type: 'Boolean' }
+  end
 end
 ```
 

data/lib/grape_oas/api_model/api.rb

@@ -38,6 +38,10 @@ module GrapeOAS
       def add_tags(*tags)
         @tag_defs.merge(tags)
       end
+
+      def builder_cache
+        @builder_cache ||= {}
+      end
     end
   end
 end

data/lib/grape_oas/api_model/schema.rb

@@ -11,7 +11,7 @@ module GrapeOAS
       VALID_ATTRIBUTES = %i[
         canonical_name type format properties items description
         required nullable enum additional_properties unevaluated_properties defs
-        examples extensions
+        examples default extensions
         min_length max_length pattern
         minimum maximum exclusive_minimum exclusive_maximum
         min_items max_items
@@ -51,10 +51,25 @@ module GrapeOAS
       end
 
       def add_property(name, schema, required: false)
-        @properties[name.to_s] = schema
-        @required << name.to_s if required
+        key = name.to_s
+        @properties[key] = schema
+        @required << key if required && !@required.include?(key)
         schema
       end
+
+      protected
+
+      # Ensure dup produces an independent copy — without this, the shallow
+      # copy shares @properties, @required, and @defs with the original.
+      # Property values are duped one level deep (via transform_values(&:dup)),
+      # which triggers initialize_copy recursively on each nested Schema,
+      # producing a full deep copy of the property tree.
+      def initialize_copy(source)
+        super
+        @properties = source.properties.transform_values(&:dup)
+        @required   = source.required.dup
+        @defs       = source.defs.dup
+      end
     end
   end
 end

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

@@ -57,6 +57,16 @@ module GrapeOAS
         end
 
         def default_format_from_app_or_api
+          return uncached_default_format_from_app_or_api unless api.respond_to?(:builder_cache)
+
+          cache = api.builder_cache
+          key = [:default_format, app.object_id]
+          return cache[key] if cache.key?(key)
+
+          cache[key] = uncached_default_format_from_app_or_api
+        end
+
+        def uncached_default_format_from_app_or_api
           return api.default_format if api.respond_to?(:default_format)
           return app.default_format if app_responds_to?(:default_format)
 
@@ -66,6 +76,17 @@ module GrapeOAS
         end
 
         def content_types_from_app_or_api(default_format)
+          return uncached_content_types_from_app_or_api(default_format) unless api.respond_to?(:builder_cache)
+
+          cache = api.builder_cache
+          key = [:content_types, app.object_id, default_format]
+          return cache[key] if cache.key?(key)
+
+          value = uncached_content_types_from_app_or_api(default_format)
+          cache[key] = value.is_a?(Hash) ? value.dup.freeze : value
+        end
+
+        def uncached_content_types_from_app_or_api(default_format)
           source = if api.respond_to?(:content_types)
                      api.content_types
                    elsif app_responds_to?(:content_types)

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

@@ -12,11 +12,8 @@ module GrapeOAS
       # Centralizes Ruby type to OpenAPI schema type resolution.
       # Used by request builders and introspectors to avoid duplicated type switching logic.
       module TypeResolver
-        # Regex to match Grape's typed array notation like "[String]", "[Integer]", "[MyModule::MyType]"
-        TYPED_ARRAY_PATTERN = /\A\[(\w+(?:::\w+)*)\]\z/
-
-        # Regex to match Grape's multi-type notation like "[String, Integer]", "[String, Float]"
-        MULTI_TYPE_PATTERN = /\A\[(\w+(?:::\w+)*(?:,\s*\w+(?:::\w+)*)+)\]\z/
+        TYPED_ARRAY_PATTERN = Constants::TypePatterns::TYPED_ARRAY
+        MULTI_TYPE_PATTERN = Constants::TypePatterns::MULTI_TYPE
 
         # 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").
@@ -65,7 +62,7 @@ module GrapeOAS
           return nil unless type.is_a?(String)
 
           match = type.match(TYPED_ARRAY_PATTERN)
-          match ? match[1] : nil
+          match ? match[:inner] : nil
         end
 
         # Checks if type is a multi-type notation like "[String, Integer]"

data/lib/grape_oas/api_model_builders/request.rb

@@ -134,20 +134,29 @@ module GrapeOAS
         validations = setting.route[:saved_validations]
         return unless validations.is_a?(Array)
 
-        # Find ContractScopeValidator which holds the Dry contract/schema
-        contract_validation = validations.find do |v|
-          next unless v.is_a?(Hash)
-
-          validator_class = v[:validator_class]
-          validator_class.is_a?(Class) &&
-            defined?(Grape::Validations::Validators::ContractScopeValidator) &&
-            validator_class <= Grape::Validations::Validators::ContractScopeValidator
-        end
+        # Find ContractScopeValidator which holds the Dry contract/schema.
+        # Grape < 3.2 stores hashes: {validator_class: ..., opts: {schema: ...}}
+        # Grape >= 3.2 stores validator instances directly (instantiated at definition time)
+        return unless defined?(Grape::Validations::Validators::ContractScopeValidator)
 
-        return unless contract_validation
+        validations.each do |v|
+          case v
+          when Hash
+            next unless v[:validator_class].is_a?(Class) &&
+                        v[:validator_class] <= Grape::Validations::Validators::ContractScopeValidator
+
+            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)
+            GrapeOAS.logger&.warn("ContractScopeValidator found but @schema is nil") if schema.nil?
+            return schema
+          end
+        end
 
-        # The contract instance is stored in opts[:schema]
-        contract_validation.dig(:opts, :schema)
+        nil
       end
 
       def build_contract_schema

data/lib/grape_oas/api_model_builders/request_params_support/param_location_resolver.rb

@@ -65,7 +65,7 @@ module GrapeOAS
           # Precedence (highest to lowest):
           #   1. `param_type` option (e.g., `documentation: { param_type: 'query' }`)
           #   2. `in` option (e.g., `documentation: { in: 'query' }`)
-          #   3. Falls back to "query" if neither is specified
+          #   3. Defaults to "body" for write methods (POST/PUT/PATCH), "query" for read methods
           #
           # Note: If both `param_type` and `in` are specified, `param_type` takes precedence.
           # For example, `{ param_type: 'query', in: 'body' }` will be treated as query.
@@ -81,7 +81,12 @@ module GrapeOAS
 
             # Support both param_type and in for grape-swagger compatibility
             # param_type takes precedence over in when both are specified
-            (param_type || in_location)&.to_s&.downcase || "query"
+            explicit_location = (param_type || in_location)&.to_s&.downcase
+            return explicit_location if explicit_location
+
+            # Default: body for write methods (POST/PUT/PATCH), query for read methods (GET/DELETE/HEAD)
+            http_method = route.request_method.to_s.downcase
+            Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method) ? "query" : "body"
           end
         end
       end

data/lib/grape_oas/api_model_builders/request_params_support/param_schema_builder.rb

@@ -33,6 +33,11 @@ module GrapeOAS
 
           return build_entity_array_schema(spec, raw_type, doc_type) if entity_array_type?(type_source, doc_type, spec)
           return build_doc_entity_array_schema(doc_type) if doc[:is_array] && grape_entity?(doc_type)
+
+          # is_array: true on a typed array like "[String]" is redundant and would
+          # double-wrap it as Array<Array<...>> via build_primitive_array_schema.
+          return GrapeOAS.type_resolvers.build_schema(raw_type) if doc[:is_array] && extract_typed_array_member(raw_type)
+          return build_primitive_array_schema(doc_type, raw_type) if doc[:is_array]
           return build_entity_schema(doc_type) if grape_entity?(doc_type)
           return build_entity_schema(raw_type) if grape_entity?(raw_type)
           return build_elements_array_schema(spec) if array_with_elements?(raw_type, spec)
@@ -92,6 +97,15 @@ module GrapeOAS
           ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
         end
 
+        def build_primitive_array_schema(doc_type, raw_type)
+          type_source = doc_type || raw_type
+          item_type = resolve_schema_type(type_source)
+          ApiModel::Schema.new(
+            type: Constants::SchemaTypes::ARRAY,
+            items: ApiModel::Schema.new(type: item_type, format: Constants.format_for_type(type_source)),
+          )
+        end
+
         def build_simple_array_schema
           ApiModel::Schema.new(
             type: Constants::SchemaTypes::ARRAY,
@@ -191,7 +205,7 @@ module GrapeOAS
           klass = Object.const_get(const_name, false)
           klass if klass.is_a?(Class) && klass <= Grape::Entity
         rescue NameError => e
-          warn "[grape-oas] Could not resolve entity constant '#{const_name}': #{e.message}"
+          GrapeOAS.logger.warn("Could not resolve entity constant '#{const_name}': #{e.message}")
           nil
         end
       end

data/lib/grape_oas/api_model_builders/request_params_support/schema_enhancer.rb

@@ -19,8 +19,9 @@ module GrapeOAS
 
           apply_additional_properties(schema, doc)
           apply_format_and_example(schema, doc)
-          apply_constraints(schema, doc)
+          SchemaConstraints.apply(schema, doc)
           apply_values(schema, spec)
+          apply_default(schema, spec, doc)
         end
 
         # Extracts nullable flag from a documentation hash.
@@ -45,45 +46,40 @@ module GrapeOAS
             schema.defs = defs if defs.is_a?(Hash) && schema.respond_to?(:defs=)
           end
 
+          def apply_default(schema, spec, doc)
+            return unless schema.respond_to?(:default=)
+
+            if spec.key?(:default)
+              schema.default = spec[:default]
+            elsif doc.key?(:default)
+              schema.default = doc[:default]
+            end
+          end
+
           def apply_format_and_example(schema, doc)
             schema.format = doc[:format] if doc[:format] && schema.respond_to?(:format=)
             schema.examples = doc[:example] if doc[:example] && schema.respond_to?(:examples=)
           end
 
-          def apply_constraints(schema, doc)
-            schema.minimum = doc[:minimum] if doc.key?(:minimum) && schema.respond_to?(:minimum=)
-            schema.maximum = doc[:maximum] if doc.key?(:maximum) && schema.respond_to?(:maximum=)
-            schema.min_length = doc[:min_length] if doc.key?(:min_length) && schema.respond_to?(:min_length=)
-            schema.max_length = doc[:max_length] if doc.key?(:max_length) && schema.respond_to?(:max_length=)
-            schema.pattern = doc[:pattern] if doc.key?(:pattern) && schema.respond_to?(:pattern=)
-          end
-
-          # Applies values from spec[:values] - converts Range to min/max,
-          # evaluates Proc (arity 0), and sets enum for arrays.
-          # Skips Proc/Lambda validators (arity > 0) used for custom validation.
-          # For array schemas, applies enum to items (since values constrain array elements).
-          # For oneOf schemas, applies enum to each non-null variant.
           def apply_values(schema, spec)
-            values = spec[:values]
+            values = ValuesNormalizer.normalize(spec[:values], context: "parameter values")
             return unless values
 
-            # Handle Hash format { value: ..., message: ... } - extract the value
-            values = values[:value] if values.is_a?(Hash) && values.key?(:value)
-
-            # Handle Proc/Lambda
-            if values.respond_to?(:call)
-              # Skip validators (arity > 0) - they validate individual values
-              return if values.arity != 0
-
-              # Evaluate arity-0 procs - they return enum arrays
-              values = values.call
-            end
-
             if values.is_a?(Range)
-              apply_range_values(schema, values)
-            else
-              enum_values = defined?(Set) && values.is_a?(Set) ? values.to_a : values
-              apply_enum_values(schema, enum_values) if enum_values.is_a?(Array) && enum_values.any?
+              if one_of_schema?(schema)
+                schema.one_of.each do |variant|
+                  next if null_type_schema?(variant)
+                  next unless range_compatible_with_schema?(values, variant)
+
+                  RangeUtils.apply_to_schema(variant, values)
+                end
+              elsif array_schema_with_items?(schema)
+                RangeUtils.apply_to_schema(schema.items, values)
+              else
+                RangeUtils.apply_to_schema(schema, values)
+              end
+            elsif values.is_a?(Array) && !values.empty?
+              apply_enum_values(schema, values)
             end
           end
 
@@ -98,7 +94,7 @@ module GrapeOAS
                 compatible_values = filter_compatible_values(variant, values)
 
                 # Only apply enum if there are compatible values
-                variant.enum = compatible_values if compatible_values.any? && variant.respond_to?(:enum=)
+                variant.enum = compatible_values if !compatible_values.empty? && variant.respond_to?(:enum=)
               end
             elsif array_schema_with_items?(schema)
               # For array schemas, apply enum to items (values constrain array elements)
@@ -110,7 +106,7 @@ module GrapeOAS
           end
 
           def one_of_schema?(schema)
-            schema.respond_to?(:one_of) && schema.one_of.is_a?(Array) && schema.one_of.any?
+            schema.respond_to?(:one_of) && schema.one_of.is_a?(Array) && !schema.one_of.empty?
           end
 
           def null_type_schema?(schema)
@@ -159,26 +155,14 @@ module GrapeOAS
             end
           end
 
-          # Converts a Range to minimum/maximum constraints.
-          # For numeric ranges (Integer, Float), uses min/max.
-          # For other ranges (e.g., 'a'..'z'), expands to enum array.
-          # Handles endless/beginless ranges (e.g., 1.., ..10).
-          def apply_range_values(schema, range)
-            first_val = range.begin
-            last_val = range.end
-
-            if first_val.is_a?(Numeric) || last_val.is_a?(Numeric)
-              schema.minimum = first_val if first_val && schema.respond_to?(:minimum=)
-              schema.maximum = last_val if last_val && schema.respond_to?(:maximum=)
-            elsif first_val && last_val && schema.respond_to?(:enum=)
-              # Non-numeric bounded range (e.g., 'a'..'z') - expand to enum
-              schema.enum = range.to_a
-            end
-          end
-
           def extract_defs(doc)
             doc[:defs] || doc[:$defs]
           end
+
+          def range_compatible_with_schema?(range, schema)
+            numeric_type = RangeUtils::NUMERIC_TYPES.include?(schema.type)
+            RangeUtils.numeric_range?(range) ? numeric_type : !numeric_type
+          end
         end
       end
     end

data/lib/grape_oas/constants.rb

@@ -47,6 +47,19 @@ module GrapeOAS
       EXTENSION = :extension
     end
 
+    # Maximum number of elements to expand from a non-numeric Range into an enum array.
+    # Prevents OOM on wide string ranges (e.g. "a".."zzzzzz").
+    MAX_ENUM_RANGE_SIZE = 100
+
+    # Regex patterns for Grape's stringified type notations.
+    # Grape converts `type: [SomeClass]` to "[SomeClass]" and
+    # `type: [String, Integer]` to "[String, Integer]" for documentation.
+    module TypePatterns
+      CONST_NAME = /(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*/
+      TYPED_ARRAY = /\A\[(?<inner>#{CONST_NAME})\]\z/
+      MULTI_TYPE = /\A\[(#{CONST_NAME}(?:,\s*#{CONST_NAME})+)\]\z/
+    end
+
     # Default values for OpenAPI spec when not provided by user
     module Defaults
       LICENSE_NAME = "Proprietary"

data/lib/grape_oas/doc_key_normalizer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  # Normalizes documentation hash keys so callers can use symbol access
+  # uniformly. String keys that look like OpenAPI extensions ("x-*") are
+  # kept as strings; all other keys are converted to symbols.
+  module DocKeyNormalizer
+    def self.normalize(doc)
+      return doc if doc.empty?
+
+      doc.transform_keys { |k| k.to_s.start_with?("x-") ? k.to_s : k.to_sym }
+    end
+  end
+end

data/lib/grape_oas/exporter/oas2/parameter.rb

@@ -78,6 +78,7 @@ module GrapeOAS
           result["maxItems"] = schema.max_items if schema.respond_to?(:max_items) && !schema.max_items.nil?
           result["pattern"] = schema.pattern if schema.respond_to?(:pattern) && schema.pattern
           result["enum"] = normalize_enum(schema.enum, result["type"]) if schema.respond_to?(:enum) && schema.enum
+          result["default"] = schema.default if schema.respond_to?(:default) && !schema.default.nil?
         end
 
         def normalize_enum(enum_vals, type)

data/lib/grape_oas/exporter/oas2/schema.rb

@@ -33,28 +33,39 @@ module GrapeOAS
             "format" => @schema.format,
             "description" => @schema.description&.to_s,
             "properties" => build_properties(@schema.properties),
-            "items" => (@schema.items ? build_schema_or_ref(@schema.items) : nil),
             "enum" => normalize_enum(@schema.enum, @schema.type)
           }
+          if @schema.items
+            schema_hash["items"] = build_schema_or_ref(@schema.items, include_metadata: false)
+            if !schema_hash["description"] && @schema.items.respond_to?(:description) && @schema.items.description
+              schema_hash["description"] = @schema.items.description.to_s
+            end
+            if @schema.items.respond_to?(:canonical_name) && @schema.items.canonical_name &&
+               @nullable_strategy == Constants::NullableStrategy::EXTENSION &&
+               @schema.items.respond_to?(:nullable) && @schema.items.nullable
+              schema_hash["x-nullable"] = true
+            end
+          end
           if schema_hash["properties"].nil? || schema_hash["properties"].empty? || @schema.type != Constants::SchemaTypes::OBJECT
             schema_hash.delete("properties")
           end
           schema_hash["example"] = @schema.examples if @schema.examples
           schema_hash["required"] = @schema.required if @schema.required && !@schema.required.empty?
           schema_hash["discriminator"] = @schema.discriminator if @schema.discriminator
+          schema_hash["default"] = @schema.default unless @schema.default.nil?
           schema_hash
         end
 
-        def apply_constraints(schema_hash)
-          schema_hash["minLength"] = @schema.min_length if @schema.min_length
-          schema_hash["maxLength"] = @schema.max_length if @schema.max_length
-          schema_hash["pattern"] = @schema.pattern if @schema.pattern
-          schema_hash["minimum"] = @schema.minimum if @schema.minimum
-          schema_hash["maximum"] = @schema.maximum if @schema.maximum
-          schema_hash["exclusiveMinimum"] = @schema.exclusive_minimum if @schema.exclusive_minimum
-          schema_hash["exclusiveMaximum"] = @schema.exclusive_maximum if @schema.exclusive_maximum
-          schema_hash["minItems"] = @schema.min_items if @schema.min_items
-          schema_hash["maxItems"] = @schema.max_items if @schema.max_items
+        def apply_constraints(schema_hash, schema = @schema)
+          schema_hash["minimum"] = schema.minimum unless schema.minimum.nil?
+          schema_hash["maximum"] = schema.maximum unless schema.maximum.nil?
+          schema_hash["exclusiveMinimum"] = schema.exclusive_minimum if schema.exclusive_minimum
+          schema_hash["exclusiveMaximum"] = schema.exclusive_maximum if schema.exclusive_maximum
+          schema_hash["minLength"] = schema.min_length unless schema.min_length.nil?
+          schema_hash["maxLength"] = schema.max_length unless schema.max_length.nil?
+          schema_hash["pattern"] = schema.pattern if schema.pattern
+          schema_hash["minItems"] = schema.min_items unless schema.min_items.nil?
+          schema_hash["maxItems"] = schema.max_items unless schema.max_items.nil?
         end
 
         def apply_extensions(schema_hash)
@@ -70,27 +81,42 @@ module GrapeOAS
 
         # Build schema from oneOf/anyOf by using first type (OAS2 doesn't support these)
         # Extensions are merged to allow x-anyOf/x-oneOf for consumers that support them
+        #
+        # Only description and extensions are applied from the composition node.
+        # Type-specific attributes (default, enum, format, constraints) are omitted
+        # because they describe the multi-type composition, not the single fallback
+        # branch selected here.
         def build_first_of_schema(composition_type)
           schemas = @schema.send(composition_type)
           first_schema = schemas.first
           return {} unless first_schema
 
-          # Build the first schema as the fallback
           result = build_schema_or_ref(first_schema)
           result["description"] = @schema.description.to_s if @schema.description
           apply_extensions(result)
+          if result.key?("$ref") && result.size > 1
+            ref = { "$ref" => result.delete("$ref") }
+            result["allOf"] = [ref]
+          end
           result
         end
 
         # Build allOf schema for inheritance
         def build_all_of_schema
-          all_of_items = @schema.all_of.map do |item|
-            build_schema_or_ref(item)
-          end
+          items = @schema.all_of.map { |item| build_schema_or_ref(item) }
+          result = { "allOf" => items }
+          apply_composition_attributes(result)
+          result
+        end
 
-          result = { "allOf" => all_of_items }
+        def apply_composition_attributes(result)
+          result["type"] = @schema.type if @schema.type
+          result["format"] = @schema.format if @schema.format
           result["description"] = @schema.description.to_s if @schema.description
-          result
+          result["default"] = @schema.default unless @schema.default.nil?
+          result["enum"] = normalize_enum(@schema.enum, @schema.type) if @schema.enum
+          apply_constraints(result)
+          apply_extensions(result)
         end
 
         def build_properties(properties)
@@ -102,16 +128,22 @@ module GrapeOAS
           end
         end
 
-        def build_schema_or_ref(schema)
+        def build_schema_or_ref(schema, include_metadata: true)
           if schema.respond_to?(:canonical_name) && schema.canonical_name
             @ref_tracker << schema.canonical_name if @ref_tracker
             ref_name = schema.canonical_name.gsub("::", "_")
             ref_hash = { "$ref" => "#/definitions/#{ref_name}" }
+            return ref_hash unless include_metadata
+
             result = {}
             if @nullable_strategy == Constants::NullableStrategy::EXTENSION && schema.respond_to?(:nullable) && schema.nullable
               result["x-nullable"] = true
             end
             result["description"] = schema.description.to_s if schema.description
+            result["default"] = schema.default unless schema.default.nil?
+            result["enum"] = normalize_enum(schema.enum, schema.type) if schema.enum
+            apply_constraints(result, schema)
+            result.merge!(schema.extensions) if schema.extensions
             if result.empty?
               ref_hash
             else
@@ -119,7 +151,9 @@ module GrapeOAS
               result
             end
           else
-            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            built = Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            built.delete("description") unless include_metadata
+            built
           end
         end
 

data/lib/grape_oas/exporter/oas3/parameter.rb

@@ -12,14 +12,17 @@ module GrapeOAS
 
         def build
           Array(@op.parameters).map do |param|
+            schema_hash = Schema.new(param.schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            schema_description = schema_hash.delete("description")
+            description = param.description || schema_description
             {
               "name" => param.name,
               "in" => param.location,
               "required" => param.required,
-              "description" => param.description,
+              "description" => description,
               "style" => param.style,
               "explode" => param.explode,
-              "schema" => Schema.new(param.schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+              "schema" => schema_hash
             }.compact
           end.presence
         end