grape-oas 1.4.0 → 1.5.0

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

@@ -21,6 +21,7 @@ module GrapeOAS
           sanitize_enum_against_type(schema_hash)
           apply_extensions_and_extra_properties(schema_hash)
           apply_all_constraints(schema_hash)
+          normalize_file_type!(schema_hash)
           schema_hash.compact
         end
 
@@ -37,29 +38,19 @@ module GrapeOAS
             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 &&
-               @schema.items.respond_to?(:nullable) && @schema.items.nullable
-              case @nullable_strategy
-              when Constants::NullableStrategy::KEYWORD
-                schema_hash["nullable"] = true
-              when Constants::NullableStrategy::EXTENSION
-                schema_hash["x-nullable"] = true
-              when Constants::NullableStrategy::TYPE_ARRAY
-                schema_hash["type"] = (Array(schema_hash["type"]) | ["null"])
-              end
-            end
+
           end
           schema_hash["required"] = @schema.required if @schema.required && !@schema.required.empty?
-          schema_hash["enum"] = normalize_enum(@schema.enum, schema_hash["type"]) if @schema.enum
+          schema_hash["enum"] = normalize_enum(@schema.enum, schema_hash["type"], nullable: nullable?) if @schema.enum
           schema_hash["default"] = @schema.default unless @schema.default.nil?
           schema_hash
         end
 
         def apply_examples(schema_hash)
-          return unless @schema.examples
+          return if @schema.examples.nil?
 
-          examples = Array(@schema.examples).map { |ex| coerce_example(ex, schema_hash["type"]) }
-          schema_hash["example"] = examples.first
+          type = schema_hash["type"]
+          schema_hash["example"] = coerce_example(@schema.examples, type)
         end
 
         def apply_extensions_and_extra_properties(schema_hash)
@@ -79,8 +70,72 @@ module GrapeOAS
           apply_array_constraints(schema_hash, schema)
         end
 
+        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 = GrapeOAS.schema_ref_name.call(schema.canonical_name)
+            ref_hash = { "$ref" => "#/components/schemas/#{ref_name}" }
+            unless include_metadata
+              return ref_hash unless schema_nullable?(schema)
+
+              return { "allOf" => [ref_hash] }.tap { |hash| apply_nullable_to_ref(hash, schema) }
+            end
+
+            result = {}
+            result["description"] = schema.description.to_s if schema.description
+            result["default"] = schema.default unless schema.default.nil?
+            enum_type = schema.type
+            if schema_nullable?(schema) && @nullable_strategy == Constants::NullableStrategy::TYPE_ARRAY
+              enum_type = Array(enum_type) | ["null"]
+            end
+            result["enum"] = normalize_enum(schema.enum, enum_type, nullable: schema_nullable?(schema)) if schema.enum
+            sanitize_enum_against_type(result, type: schema.type)
+            apply_all_constraints(result, schema)
+            result.merge!(schema.extensions) if schema.extensions
+            if result.empty? && !schema_nullable?(schema)
+              ref_hash
+            else
+              result["allOf"] = [ref_hash]
+              apply_nullable_to_ref(result, schema)
+              result
+            end
+          else
+            # self.class preserves the OAS version subclass (e.g. OAS31::Schema)
+            # so nested schemas get version-correct normalization.
+            built = self.class.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            strip_items_metadata(built) unless include_metadata
+            built
+          end
+        end
+
         private
 
+        # Returns the primary non-null type from a type value.
+        # Assumes at most one non-null type in the array (e.g. ["integer", "null"]).
+        def base_type_for(type)
+          type.is_a?(Array) ? (type - ["null"]).first : type
+        end
+
+        # Rewrites `type: file` (or `type: ["file", "null"]`) to the
+        # version-appropriate representation. Type detection lives here;
+        # version-specific attributes are set by `apply_file_schema_attributes!`.
+        def normalize_file_type!(hash)
+          type = hash["type"]
+          if type == Constants::SchemaTypes::FILE
+            hash["type"] = Constants::SchemaTypes::STRING
+            apply_file_schema_attributes!(hash)
+          elsif type.is_a?(Array) && type.include?(Constants::SchemaTypes::FILE)
+            hash["type"] = type.map { |t| t == Constants::SchemaTypes::FILE ? Constants::SchemaTypes::STRING : t }
+            apply_file_schema_attributes!(hash)
+          end
+        end
+
+        # OAS 3.0: files are `type: string, format: binary`.
+        # OAS 3.1 overrides this with content-* keywords.
+        def apply_file_schema_attributes!(hash)
+          hash["format"] = "binary"
+        end
+
         # Build allOf schema for inheritance
         def build_all_of_schema
           items = @schema.all_of.map { |item| build_schema_or_ref(item) }
@@ -115,10 +170,22 @@ module GrapeOAS
           result["format"] = @schema.format if @schema.format
           result["description"] = @schema.description.to_s if @schema.description
           result["default"] = @schema.default unless @schema.default.nil?
-          result["enum"] = normalize_enum(@schema.enum, result["type"]) if @schema.enum
+          result["enum"] = normalize_enum(@schema.enum, result["type"], nullable: nullable?) if @schema.enum
           sanitize_enum_against_type(result)
           apply_all_constraints(result)
-          result.merge!(@schema.extensions) if @schema.extensions
+          apply_composition_extensions(result)
+          normalize_file_type!(result)
+          result
+        end
+
+        def apply_composition_extensions(result)
+          return unless @schema.extensions
+
+          extensions = @schema.extensions.reject do |key, _value|
+            (key == "x-anyOf" && result.key?("anyOf")) ||
+              (key == "x-oneOf" && result.key?("oneOf"))
+          end
+          result.merge!(extensions)
         end
 
         # Build OAS3 discriminator object
@@ -137,8 +204,12 @@ module GrapeOAS
           end
         end
 
+        def schema_nullable?(schema)
+          schema.respond_to?(:nullable) && !!schema.nullable
+        end
+
         def nullable?
-          @schema.respond_to?(:nullable) && @schema.nullable
+          schema_nullable?(@schema)
         end
 
         def nullable_type
@@ -151,14 +222,40 @@ module GrapeOAS
         def apply_nullable(schema_hash)
           return unless nullable?
 
+          composition_key = %w[allOf oneOf anyOf].find { |k| schema_hash.key?(k) }
           case @nullable_strategy
           when Constants::NullableStrategy::KEYWORD
-            schema_hash["nullable"] = true
+            if composition_key
+              apply_keyword_null_union(schema_hash, composition_key)
+            elsif schema_hash["type"]
+              schema_hash["nullable"] = true
+            end
           when Constants::NullableStrategy::EXTENSION
             schema_hash["x-nullable"] = true
+          when Constants::NullableStrategy::TYPE_ARRAY
+            if composition_key
+              apply_null_union(schema_hash, composition_key, { "type" => "null" })
+            else
+              schema_hash["type"] = (Array(schema_hash["type"]) | ["null"])
+            end
           end
         end
 
+        # Nullable must accompany a type, and every composition constraint must
+        # also admit null. The enum keeps the extra branch from allowing objects.
+        def apply_keyword_null_union(hash, key)
+          hash["nullable"] = true if hash["type"]
+          apply_null_union(hash, key, keyword_null_only_branch)
+        end
+
+        def apply_null_union(hash, key, null_branch)
+          raise ArgumentError, "#{key} must be an Array of schemas" unless hash[key].is_a?(Array)
+
+          branch = { key => hash.delete(key) }
+          branch["discriminator"] = hash.delete("discriminator") if hash.key?("discriminator")
+          hash["anyOf"] = [branch, null_branch]
+        end
+
         def build_properties(properties)
           return nil unless properties
           return nil if properties.empty?
@@ -168,70 +265,80 @@ module GrapeOAS
           end
         end
 
-        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" => "#/components/schemas/#{ref_name}" }
-            return ref_hash unless include_metadata
-
-            result = {}
-            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
-            sanitize_enum_against_type(result, type: schema.type)
-            apply_all_constraints(result, schema)
-            result.merge!(schema.extensions) if schema.extensions
-            apply_nullable_to_ref(result, schema)
-            if result.empty?
-              ref_hash
-            else
-              result["allOf"] = [ref_hash]
-              result
-            end
-          else
-            built = Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
-            strip_items_metadata(built) unless include_metadata
-            built
-          end
-        end
-
         def strip_items_metadata(hash)
           hash.delete("description")
         end
 
         def apply_nullable_to_ref(result, schema)
-          return unless schema.respond_to?(:nullable) && schema.nullable
+          return unless schema_nullable?(schema)
 
           case @nullable_strategy
           when Constants::NullableStrategy::KEYWORD
-            result["nullable"] = true
+            apply_ref_null_union(result, keyword_null_only_branch, typed_nullable: true)
           when Constants::NullableStrategy::EXTENSION
             result["x-nullable"] = true
           when Constants::NullableStrategy::TYPE_ARRAY
-            # TYPE_ARRAY encodes nullability via the "type" field, which cannot be
-            # applied to a $ref schema. For refs we intentionally do nothing.
-            nil
+            apply_ref_null_union(result, { "type" => "null" }, typed_nullable: false)
           end
         end
 
-        def normalize_enum(enum_vals, type)
+        # Prefer a bare $ref as the non-null alternative when allOf would only
+        # wrap that single ref (OAS 3.0 needs allOf only for $ref siblings).
+        def apply_ref_null_union(result, null_branch, typed_nullable:)
+          allof = result["allOf"]
+          if bare_single_ref_allof?(allof)
+            ref = result.delete("allOf").first
+            result["nullable"] = true if typed_nullable && result["type"]
+            result["anyOf"] = [ref, null_branch]
+          elsif typed_nullable
+            apply_keyword_null_union(result, "allOf")
+          else
+            apply_null_union(result, "allOf", null_branch)
+          end
+        end
+
+        def bare_single_ref_allof?(allof)
+          allof.is_a?(Array) && allof.size == 1 && allof.first.is_a?(Hash) && allof.first.keys == ["$ref"]
+        end
+
+        def keyword_null_only_branch
+          { "type" => Constants::SchemaTypes::OBJECT, "nullable" => true, "enum" => [nil] }
+        end
+
+        def normalize_enum(enum_vals, type, nullable: false)
           return nil unless enum_vals.is_a?(Array)
 
-          coerced = enum_vals.map do |v|
-            case type
-            when Constants::SchemaTypes::INTEGER then v.to_i if v.respond_to?(:to_i)
-            when Constants::SchemaTypes::NUMBER then v.to_f if v.respond_to?(:to_f)
-            else v
-            end
-          end.compact
+          nullable = (nullable || (type.is_a?(Array) && type.include?(Constants::SchemaTypes::NULL))) &&
+                     enum_null_supported?(type)
+          resolved_type = base_type_for(type)
+
+          has_nil = nullable && enum_vals.include?(nil)
+
+          result = enum_vals.each_with_object([]) do |v, acc|
+            next if v.nil?
 
-          result = coerced.uniq
+            coerced_v = case resolved_type
+                        when Constants::SchemaTypes::INTEGER then v.to_i if v.respond_to?(:to_i)
+                        when Constants::SchemaTypes::NUMBER then v.to_f if v.respond_to?(:to_f)
+                        else v
+                        end
+            acc << coerced_v unless coerced_v.nil?
+          end
+
+          result.uniq!
+          result.push(nil) if has_nil
           return nil if result.empty?
 
           result
         end
 
+        def enum_null_supported?(type)
+          return true if @nullable_strategy == Constants::NullableStrategy::KEYWORD
+
+          @nullable_strategy == Constants::NullableStrategy::TYPE_ARRAY &&
+            type.is_a?(Array) && type.include?(Constants::SchemaTypes::NULL)
+        end
+
         def apply_numeric_constraints(hash, schema = @schema)
           hash["minimum"] = schema.minimum unless schema.minimum.nil?
           hash["maximum"] = schema.maximum unless schema.maximum.nil?
@@ -260,55 +367,96 @@ module GrapeOAS
         def apply_array_constraints(hash, schema = @schema)
           hash["minItems"] = schema.min_items unless schema.min_items.nil?
           hash["maxItems"] = schema.max_items unless schema.max_items.nil?
+          hash["uniqueItems"] = true if schema.unique_items
         end
 
-        # Ensure enum values match the declared type; drop enum if incompatible to avoid invalid specs
+        # Ensure enum values match the declared type; drop enum if incompatible to avoid invalid specs.
         def sanitize_enum_against_type(hash, type: nil)
+          # A literal `"enum" => nil` (from a nil-only enum on a non-nullable schema) must not
+          # survive: composition/$ref callers never `.compact` their result hash, so an unguarded
+          # nil would leak as `enum: null` and, for $ref, would make `result.empty?` false and
+          # force an unwanted `allOf` wrapper.
+          return hash.delete("enum") if hash.key?("enum") && hash["enum"].nil?
+
           enum_vals = hash["enum"]
           type_val = type || hash["type"]
           return unless enum_vals && type_val
 
-          base_type = if type_val.is_a?(Array)
-                        (type_val - ["null"]).first
-                      else
-                        type_val
-                      end
+          base = base_type_for(type_val)
+          return hash.delete("enum") if base.nil? || base == Constants::SchemaTypes::ARRAY || base == Constants::SchemaTypes::OBJECT
 
-          # Remove enum for unsupported base types or mismatches
-          case base_type
-          when Constants::SchemaTypes::ARRAY, Constants::SchemaTypes::OBJECT, nil
-            hash.delete("enum")
+          non_nil_vals = enum_vals.compact
+
+          case base
           when Constants::SchemaTypes::INTEGER
-            hash.delete("enum") unless enum_vals.all?(Integer)
+            hash.delete("enum") unless non_nil_vals.all?(Integer)
           when Constants::SchemaTypes::NUMBER
-            hash.delete("enum") unless enum_vals.all?(Numeric)
+            hash.delete("enum") unless non_nil_vals.all?(Numeric)
           when Constants::SchemaTypes::BOOLEAN
-            hash.delete("enum") unless enum_vals.all? { |v| [true, false].include?(v) }
+            hash.delete("enum") unless non_nil_vals.all? { |v| v == true || v == false } # rubocop:disable Style/MultipleComparison
           else # string and fallback
-            hash.delete("enum") unless enum_vals.all?(String)
+            hash.delete("enum") unless non_nil_vals.all?(String)
           end
         end
 
         def coerce_example(example, type_val)
-          base_type = if type_val.is_a?(Array)
-                        (type_val - ["null"]).first
-                      else
-                        type_val
-                      end
+          return nil if example.nil?
+
+          base_type = base_type_for(type_val)
+          case base_type
+          when Constants::SchemaTypes::ARRAY
+            return example if example.is_a?(Array)
+
+            return nil
+          when Constants::SchemaTypes::OBJECT
+            return example if example.is_a?(Hash)
+
+            return nil
+          when nil
+            return example
+          else
+            return nil if example.is_a?(Hash)
+
+            if example.is_a?(Array)
+              return nil unless example.size == 1
+
+              example = example.first
+            end
+          end
 
           case base_type
           when Constants::SchemaTypes::INTEGER
-            example.to_i
+            coerce_integer_example(example)
           when Constants::SchemaTypes::NUMBER
-            example.to_f
+            coerce_number_example(example)
           when Constants::SchemaTypes::BOOLEAN
-            example == true || example.to_s == "true"
-          when Constants::SchemaTypes::STRING, nil
+            case example
+            when true, false
+              example
+            when String
+              return true if example.casecmp("true").zero?
+              return false if example.casecmp("false").zero?
+
+              nil
+            end
+          when Constants::SchemaTypes::STRING
             example.to_s
           else
             example
           end
         end
+
+        def coerce_integer_example(example)
+          example.is_a?(String) ? Integer(example, 10) : Integer(example)
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def coerce_number_example(example)
+          Float(example)
+        rescue ArgumentError, TypeError
+          nil
+        end
       end
     end
   end

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

@@ -13,10 +13,12 @@ module GrapeOAS
         def build
           hash = super
 
-          # swap example -> examples if present
+          # swap example -> examples if present. The OAS3 `example` is a single
+          # value, so wrap it as a one-element list (a value that is itself an
+          # array is one array-valued example, not many examples).
           if hash.key?("example")
             ex = hash.delete("example")
-            hash["examples"] ||= ex
+            hash["examples"] = [ex] unless hash.key?("examples")
           end
           normalize_examples!(hash)
           hash
@@ -24,6 +26,14 @@ module GrapeOAS
 
         private
 
+        # OAS 3.1: files use JSON Schema content-* keywords instead of
+        # the OAS 3.0 `format: binary` convention.
+        def apply_file_schema_attributes!(hash)
+          hash.delete("format")
+          hash["contentMediaType"] = "application/octet-stream"
+          hash["contentEncoding"] = "binary"
+        end
+
         # Ensure examples is always an array and recurse into nested schemas
         def normalize_examples!(hash)
           hash["examples"] = [hash["examples"]].compact if hash.key?("examples") && !hash["examples"].is_a?(Array)

data/lib/grape_oas/exporter/oas31_schema.rb

@@ -29,7 +29,7 @@ module GrapeOAS
       def nullable_strategy
         # OAS 3.1 always uses JSON Schema null unions ("type": ["string", "null"]).
         # The "nullable" keyword and "x-nullable" extension are not valid in OAS 3.1.
-        Constants::NullableStrategy::TYPE_ARRAY
+        Constants::NullableStrategy::OAS31_DEFAULT
       end
     end
   end

data/lib/grape_oas/exporter/oas3_schema.rb

@@ -20,6 +20,7 @@ module GrapeOAS
           "tags" => build_tags,
           "paths" => OAS3::Paths.new(@api, @ref_tracker,
                                      nullable_strategy: nullable_strategy,
+                                     schema_builder: schema_builder,
                                      suppress_default_error_response: @api.suppress_default_error_response,).build,
           "components" => build_components,
           "security" => build_security
@@ -88,7 +89,7 @@ module GrapeOAS
 
           processed << canonical_name
 
-          ref_name = canonical_name.gsub("::", "_")
+          ref_name = GrapeOAS.schema_ref_name.call(canonical_name)
           schema = find_schema_by_canonical_name(canonical_name)
           if schema
             schemas[ref_name] =
@@ -120,7 +121,7 @@ module GrapeOAS
       end
 
       def nullable_strategy
-        @api.nullable_strategy || Constants::NullableStrategy::KEYWORD
+        @api.nullable_strategy || Constants::NullableStrategy::OAS3_DEFAULT
       end
     end
   end

data/lib/grape_oas/introspectors/entity_introspector.rb

@@ -119,7 +119,8 @@ module GrapeOAS
       end
 
       def entity_doc
-        @entity_class.respond_to?(:documentation) ? (@entity_class.documentation || {}) : {}
+        doc = @entity_class.respond_to?(:documentation) ? (@entity_class.documentation || {}) : {}
+        DocKeyNormalizer.normalize(doc)
       rescue NoMethodError
         {}
       end

data/lib/grape_oas/introspectors/entity_introspector_support/exposure_processor.rb

@@ -19,8 +19,6 @@ module GrapeOAS
         # @param schema [ApiModel::Schema] the schema to populate
         def add_exposures_to_schema(schema)
           exposures.each do |exposure|
-            next unless exposed?(exposure)
-
             add_exposure_to_schema(schema, exposure)
           end
         end
@@ -73,8 +71,11 @@ module GrapeOAS
         #
         # @param exposure the entity exposure
         # @return [Boolean] true if exposed
-        def exposed?(_exposure)
-          true
+        def exposed?(exposure)
+          doc = normalize_doc_keys(exposure.documentation || {})
+          hidden = doc[:hidden]
+          hidden = hidden.call if hidden.respond_to?(:call)
+          !hidden
         end
 
         # Checks if an exposure is conditional.
@@ -128,6 +129,8 @@ module GrapeOAS
         end
 
         def add_exposure_to_schema(schema, exposure)
+          return unless exposed?(exposure)
+
           doc = normalize_doc_keys(exposure.documentation || {})
           opts = exposure_options(exposure)
 
@@ -155,7 +158,9 @@ module GrapeOAS
           is_array = doc[:is_array]
           return prop_schema unless is_array
 
-          ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: prop_schema)
+          array_schema = ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: prop_schema)
+          array_schema.examples = doc[:example] if array_valued_example?(doc)
+          array_schema
         end
 
         # Detects block-based nesting exposures (NestingExposure) that should become
@@ -178,6 +183,8 @@ module GrapeOAS
           nesting_accum = {}
           nesting_required = Hash.new { |h, k| h[k] = [] }
           Array(exposure.nested_exposures).each do |child_exposure|
+            next unless exposed?(child_exposure)
+
             if nesting_exposure?(child_exposure)
               key = child_exposure.key.to_s
               child_doc = normalize_doc_keys(child_exposure.documentation || {})
@@ -200,7 +207,16 @@ module GrapeOAS
         end
 
         def apply_exposure_properties(schema, doc)
-          schema.nullable = doc[:nullable] || false
+          nullable = PropertyExtractor.extract_nullable(doc)
+          if nullable && schema.canonical_name
+            # Don't mutate the shared cached entity schema. Create a wrapper with
+            # all_of so the exporter emits { nullable: true, allOf: [{ $ref }] }.
+            # collect_refs traverses all_of and registers the original schema as a
+            # component, keeping its definition free of this property's nullable.
+            schema = ApiModel::Schema.new(nullable: true, all_of: [schema])
+          else
+            schema.nullable = nullable
+          end
           raw_values = doc[:values]
           if raw_values
             normalized = ValuesNormalizer.normalize(raw_values, context: "entity exposure values")
@@ -212,7 +228,7 @@ module GrapeOAS
           end
           schema.description = doc[:desc] if doc[:desc]
           schema.format = doc[:format] if doc[:format]
-          schema.examples = doc[:example] if schema.respond_to?(:examples=) && doc[:example]
+          schema = apply_example_to_schema(schema, doc[:example]) if doc.key?(:example) && !array_valued_example?(doc)
           schema.additional_properties = doc[:additional_properties] if doc.key?(:additional_properties)
           schema.unevaluated_properties = doc[:unevaluated_properties] if doc.key?(:unevaluated_properties)
           defs = doc[:defs] || doc[:$defs]
@@ -223,17 +239,24 @@ module GrapeOAS
         end
 
         # Cached entity schemas (via using:) are shared across all exposures that
-        # reference the same entity — dup before setting enum to avoid mutating
-        # the shared schema; emit a warning so users know a dup occurred.
+        # reference the same entity — dup before mutating them (enum, example, ...)
+        # to avoid corrupting the shared schema; emit a warning so users know a
+        # dup occurred.
         #
+        # @return [ApiModel::Schema] a dup of schema with canonical_name cleared
+        def dup_cached_schema(schema, reason:, value:)
+          GrapeOAS.logger.warn(
+            "Duplicating cached schema '#{schema.canonical_name}' to apply #{reason} #{value.inspect}",
+          )
+          dup = schema.dup
+          dup.canonical_name = nil
+          dup
+        end
+
         # @return [ApiModel::Schema] the schema (or a dup) with enum applied
         def apply_enum_to_schema(schema, values)
           if schema.respond_to?(:canonical_name) && schema.canonical_name
-            GrapeOAS.logger.warn(
-              "Duplicating cached schema '#{schema.canonical_name}' to apply enum #{values.inspect}",
-            )
-            schema = schema.dup
-            schema.canonical_name = nil
+            schema = dup_cached_schema(schema, reason: "enum", value: values)
             schema.enum = values
             return schema
           end
@@ -241,13 +264,9 @@ module GrapeOAS
           if schema.type == Constants::SchemaTypes::ARRAY &&
              schema.respond_to?(:items) && schema.items
             if schema.items.respond_to?(:canonical_name) && schema.items.canonical_name
-              GrapeOAS.logger.warn(
-                "Duplicating cached schema '#{schema.items.canonical_name}' to apply enum #{values.inspect}",
-              )
-              schema = schema.dup
-              items_dup = schema.items.dup
-              items_dup.canonical_name = nil
+              items_dup = dup_cached_schema(schema.items, reason: "enum", value: values)
               items_dup.enum = values
+              schema = schema.dup
               schema.items = items_dup
             else
               schema.items.enum = values
@@ -258,6 +277,22 @@ module GrapeOAS
           schema
         end
 
+        def apply_example_to_schema(schema, example)
+          return schema unless schema.respond_to?(:examples=)
+
+          if schema.respond_to?(:canonical_name) && schema.canonical_name
+            schema = dup_cached_schema(schema, reason: "example", value: example)
+          end
+          schema.examples = example
+          schema
+        end
+
+        # True when doc[:example] describes the whole array (not a single item),
+        # i.e. is_array: true and the example is itself an Array.
+        def array_valued_example?(doc)
+          doc[:is_array] && doc[:example].is_a?(Array)
+        end
+
         def normalize_doc_keys(doc)
           DocKeyNormalizer.normalize(doc)
         end