grape-oas 1.3.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,28 +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)
@@ -72,34 +64,92 @@ module GrapeOAS
           schema_hash["discriminator"] = build_discriminator if @schema.discriminator
         end
 
-        def apply_all_constraints(schema_hash)
-          apply_numeric_constraints(schema_hash)
-          apply_string_constraints(schema_hash)
-          apply_array_constraints(schema_hash)
+        def apply_all_constraints(schema_hash, schema = @schema)
+          apply_numeric_constraints(schema_hash, schema)
+          apply_string_constraints(schema_hash, schema)
+          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
 
-        # Build allOf schema for inheritance
-        def build_all_of_schema
-          all_of_items = @schema.all_of.map do |item|
-            build_schema_or_ref(item)
+        # 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
 
-          result = { "allOf" => all_of_items }
-          result["description"] = @schema.description.to_s if @schema.description
+        # 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) }
+          result = { "allOf" => items }
+          apply_composition_attributes(result)
           apply_nullable(result)
           result
         end
 
         # Build oneOf schema for polymorphism
         def build_one_of_schema
-          one_of_items = @schema.one_of.map do |item|
-            build_schema_or_ref(item)
-          end
-
-          result = { "oneOf" => one_of_items }
-          result["description"] = @schema.description.to_s if @schema.description
+          items = @schema.one_of.map { |item| build_schema_or_ref(item) }
+          result = { "oneOf" => items }
+          apply_composition_attributes(result)
           result["discriminator"] = build_discriminator if @schema.discriminator
           apply_nullable(result)
           result
@@ -107,17 +157,37 @@ module GrapeOAS
 
         # Build anyOf schema for polymorphism
         def build_any_of_schema
-          any_of_items = @schema.any_of.map do |item|
-            build_schema_or_ref(item)
-          end
-
-          result = { "anyOf" => any_of_items }
-          result["description"] = @schema.description.to_s if @schema.description
+          items = @schema.any_of.map { |item| build_schema_or_ref(item) }
+          result = { "anyOf" => items }
+          apply_composition_attributes(result)
           result["discriminator"] = build_discriminator if @schema.discriminator
           apply_nullable(result)
           result
         end
 
+        def apply_composition_attributes(result)
+          result["type"] = nullable_type if @schema.type
+          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"], nullable: nullable?) if @schema.enum
+          sanitize_enum_against_type(result)
+          apply_all_constraints(result)
+          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
         def build_discriminator
           return nil unless @schema.discriminator
@@ -134,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
@@ -148,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?
@@ -165,142 +265,198 @@ 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
-            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?
+
+            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 = coerced.uniq
+          result.uniq!
+          result.push(nil) if has_nil
           return nil if result.empty?
 
           result
         end
 
-        def apply_numeric_constraints(hash)
-          hash["minimum"] = @schema.minimum unless @schema.minimum.nil?
-          hash["maximum"] = @schema.maximum unless @schema.maximum.nil?
+        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?
 
           if @nullable_strategy == Constants::NullableStrategy::TYPE_ARRAY
-            if @schema.exclusive_minimum && !@schema.minimum.nil?
-              hash["exclusiveMinimum"] = @schema.minimum
+            if schema.exclusive_minimum && !schema.minimum.nil?
+              hash["exclusiveMinimum"] = schema.minimum
               hash.delete("minimum")
             end
-            if @schema.exclusive_maximum && !@schema.maximum.nil?
-              hash["exclusiveMaximum"] = @schema.maximum
+            if schema.exclusive_maximum && !schema.maximum.nil?
+              hash["exclusiveMaximum"] = schema.maximum
               hash.delete("maximum")
             end
           else
-            hash["exclusiveMinimum"] = @schema.exclusive_minimum if @schema.exclusive_minimum
-            hash["exclusiveMaximum"] = @schema.exclusive_maximum if @schema.exclusive_maximum
+            hash["exclusiveMinimum"] = schema.exclusive_minimum if schema.exclusive_minimum
+            hash["exclusiveMaximum"] = schema.exclusive_maximum if schema.exclusive_maximum
           end
         end
 
-        def apply_string_constraints(hash)
-          hash["minLength"] = @schema.min_length unless @schema.min_length.nil?
-          hash["maxLength"] = @schema.max_length unless @schema.max_length.nil?
-          hash["pattern"] = @schema.pattern if @schema.pattern
+        def apply_string_constraints(hash, schema = @schema)
+          hash["minLength"] = schema.min_length unless schema.min_length.nil?
+          hash["maxLength"] = schema.max_length unless schema.max_length.nil?
+          hash["pattern"] = schema.pattern if schema.pattern
         end
 
-        def apply_array_constraints(hash)
-          hash["minItems"] = @schema.min_items unless @schema.min_items.nil?
-          hash["maxItems"] = @schema.max_items unless @schema.max_items.nil?
+        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
-        def sanitize_enum_against_type(hash)
+        # 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 = hash["type"]
+          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

@@ -88,12 +88,16 @@ module GrapeOAS
       def initialize_or_reuse_schema
         @registry[@entity_class] ||= ApiModel::Schema.new(
           type: Constants::SchemaTypes::OBJECT,
-          canonical_name: @entity_class.name,
+          canonical_name: resolve_canonical_name,
           description: nil,
           nullable: nil,
         )
       end
 
+      def resolve_canonical_name
+        EntityIntrospectorSupport.resolve_canonical_name(@entity_class)
+      end
+
       def populate_schema(schema)
         doc = entity_doc
         apply_schema_metadata(schema, doc)
@@ -115,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