grape-oas 1.3.0 → 1.5.0

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

@@ -4,10 +4,11 @@ module GrapeOAS
   module Exporter
     module OAS2
       class Response
-        def initialize(responses, ref_tracker = nil, nullable_strategy: nil)
+        def initialize(responses, ref_tracker = nil, nullable_strategy: nil, composition_extensions: false)
           @responses = responses
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @composition_extensions = composition_extensions
         end
 
         def build
@@ -34,10 +35,11 @@ module GrapeOAS
         def build_schema_or_ref(schema)
           if schema.respond_to?(:canonical_name) && schema.canonical_name
             @ref_tracker << schema.canonical_name if @ref_tracker
-            ref_name = schema.canonical_name.gsub("::", "_")
+            ref_name = GrapeOAS.schema_ref_name.call(schema.canonical_name)
             { "$ref" => "#/definitions/#{ref_name}" }
           else
-            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy,
+                                             composition_extensions: @composition_extensions,).build
           end
         end
 
@@ -60,7 +62,7 @@ module GrapeOAS
         end
 
         def build_examples(media_types, response_examples = nil)
-          return nil unless media_types
+          return nil if media_types.nil? || media_types.empty?
 
           mt = Array(media_types).first
           # Media type examples take precedence over response-level examples

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

@@ -4,12 +4,15 @@ module GrapeOAS
   module Exporter
     module OAS2
       class Schema
-        def initialize(schema, ref_tracker = nil, nullable_strategy: nil)
+        def initialize(schema, ref_tracker = nil, nullable_strategy: nil, composition_extensions: false)
           @schema = schema
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @composition_extensions = composition_extensions
         end
 
+        # OAS 2.0 (Swagger) natively supports `type: file`, so no
+        # file-type normalization is needed here (unlike OAS 3.x).
         def build
           return {} unless @schema
 
@@ -23,6 +26,7 @@ module GrapeOAS
 
           schema_hash = build_base_hash
           apply_constraints(schema_hash)
+          apply_compatibility_composition_extension(schema_hash)
           apply_extensions(schema_hash)
           schema_hash.compact
         end
@@ -32,9 +36,9 @@ module GrapeOAS
             "type" => @schema.type,
             "format" => @schema.format,
             "description" => @schema.description&.to_s,
-            "properties" => build_properties(@schema.properties),
-            "enum" => normalize_enum(@schema.enum, @schema.type)
+            "properties" => build_properties(@schema.properties)
           }
+          schema_hash["enum"] = normalize_enum(@schema.enum, @schema.type, nullable: nullable?) if @schema.enum
           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
@@ -52,19 +56,21 @@ module GrapeOAS
           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?
+          schema_hash["uniqueItems"] = true if schema.unique_items
         end
 
         def apply_extensions(schema_hash)
@@ -74,34 +80,60 @@ module GrapeOAS
 
         private
 
+        def apply_compatibility_composition_extension(result)
+          return unless @composition_extensions
+
+          { "x-oneOf" => @schema.one_of, "x-anyOf" => @schema.any_of }.each do |key, alternatives|
+            next unless alternatives && alternatives.size > 1
+            next if @schema.extensions&.key?(key)
+
+            result[key] = alternatives.map { |item| build_schema_or_ref(item) }
+          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
 
-        # 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
+        # OAS2 keeps a first-alternative fallback for tools that ignore extensions.
         def build_first_of_schema(composition_type)
-          schemas = @schema.send(composition_type)
+          schemas = composition_type == :any_of ? @schema.any_of : @schema.one_of
           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_compatibility_composition_extension(result)
           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["x-nullable"] = true if @nullable_strategy == Constants::NullableStrategy::EXTENSION && nullable?
-          result
+          result["default"] = @schema.default unless @schema.default.nil?
+          result["enum"] = normalize_enum(@schema.enum, @schema.type, nullable: nullable?) if @schema.enum
+          result.delete("enum") if result.key?("enum") && result["enum"].nil?
+          apply_constraints(result)
+          apply_extensions(result)
         end
 
         def build_properties(properties)
@@ -116,15 +148,18 @@ module GrapeOAS
         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_name = GrapeOAS.schema_ref_name.call(schema.canonical_name)
             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["x-nullable"] = true if @nullable_strategy == Constants::NullableStrategy::EXTENSION && schema_nullable?(schema)
             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, nullable: schema_nullable?(schema)) if schema.enum
+            result.delete("enum") if result.key?("enum") && result["enum"].nil?
+            apply_constraints(result, schema)
+            result.merge!(schema.extensions) if schema.extensions
             if result.empty?
               ref_hash
             else
@@ -132,24 +167,36 @@ module GrapeOAS
               result
             end
           else
-            built = Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            # self.class preserves any subclass so nested schemas use
+            # the version-correct builder.
+            built = self.class.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy,
+                                                         composition_extensions: @composition_extensions,).build
             built.delete("description") unless include_metadata
             built
           end
         end
 
-        def normalize_enum(enum_vals, type)
+        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
+          has_nil = nullable && enum_vals.include?(nil)
 
-          coerced.uniq
+          result = enum_vals.each_with_object([]) do |v, acc|
+            next if v.nil?
+
+            coerced_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
+            acc << coerced_v unless coerced_v.nil?
+          end
+
+          result.uniq!
+          result.push(nil) if has_nil
+          return nil if result.empty?
+
+          result
         end
       end
     end

data/lib/grape_oas/exporter/oas2_schema.rb

@@ -67,18 +67,19 @@ module GrapeOAS
       end
 
       def nullable_strategy
-        @api.nullable_strategy
+        @api.nullable_strategy || Constants::NullableStrategy::OAS2_DEFAULT
       end
 
       def build_paths
         OAS2::Paths.new(@api, @ref_tracker,
                         nullable_strategy: nullable_strategy,
+                        composition_extensions: @api.oas2_composition_extensions,
                         suppress_default_error_response: @api.suppress_default_error_response,).build
       end
 
       def build_schema_or_ref(schema)
         if schema.respond_to?(:canonical_name) && schema.canonical_name
-          ref_name = schema.canonical_name.gsub("::", "_")
+          ref_name = GrapeOAS.schema_ref_name.call(schema.canonical_name)
           @ref_tracker << schema.canonical_name
           { "$ref" => "#/definitions/#{ref_name}" }
         else
@@ -87,7 +88,8 @@ module GrapeOAS
       end
 
       def build_schema(schema)
-        OAS2::Schema.new(schema, @ref_tracker, nullable_strategy: nullable_strategy).build
+        OAS2::Schema.new(schema, @ref_tracker, nullable_strategy: nullable_strategy,
+                                               composition_extensions: @api.oas2_composition_extensions,).build
       end
 
       def build_definitions
@@ -106,9 +108,9 @@ 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)
-          definitions[ref_name] = OAS2::Schema.new(schema, @ref_tracker, nullable_strategy: nullable_strategy).build if schema
+          definitions[ref_name] = build_schema(schema) if schema
           collect_refs(schema, pending) if schema
 
           @ref_tracker.to_a.each do |cn|

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

@@ -12,10 +12,12 @@ module GrapeOAS
         def build_version_specific_fields
           strategy = @options[:nullable_strategy] || Constants::NullableStrategy::KEYWORD
 
+          schema_options = { nullable_strategy: strategy, schema_builder: @options[:schema_builder] || Schema }
+
           {
-            "parameters" => Parameter.new(@op, @ref_tracker, nullable_strategy: strategy).build,
-            "requestBody" => RequestBody.new(@op.request_body, @ref_tracker, nullable_strategy: strategy).build,
-            "responses" => Response.new(@op.responses, @ref_tracker, nullable_strategy: strategy).build
+            "parameters" => Parameter.new(@op, @ref_tracker, **schema_options).build,
+            "requestBody" => RequestBody.new(@op.request_body, @ref_tracker, **schema_options).build,
+            "responses" => Response.new(@op.responses, @ref_tracker, **schema_options).build
           }
         end
       end

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

@@ -4,22 +4,27 @@ module GrapeOAS
   module Exporter
     module OAS3
       class Parameter
-        def initialize(operation, ref_tracker = nil, nullable_strategy: Constants::NullableStrategy::KEYWORD)
+        def initialize(operation, ref_tracker = nil, nullable_strategy: Constants::NullableStrategy::KEYWORD,
+                       schema_builder: Schema)
           @op = operation
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @schema_builder = schema_builder
         end
 
         def build
           Array(@op.parameters).map do |param|
+            schema_hash = @schema_builder.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

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

@@ -12,6 +12,7 @@ module GrapeOAS
         def build_operation(operation)
           Operation.new(operation, @ref_tracker,
                         nullable_strategy: @options[:nullable_strategy] || Constants::NullableStrategy::KEYWORD,
+                        schema_builder: @options[:schema_builder] || Schema,
                         suppress_default_error_response: @options[:suppress_default_error_response],).build
         end
       end

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

@@ -4,10 +4,12 @@ module GrapeOAS
   module Exporter
     module OAS3
       class RequestBody
-        def initialize(request_body, ref_tracker = nil, nullable_strategy: Constants::NullableStrategy::KEYWORD)
+        def initialize(request_body, ref_tracker = nil, nullable_strategy: Constants::NullableStrategy::KEYWORD,
+                       schema_builder: Schema)
           @request_body = request_body
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @schema_builder = schema_builder
         end
 
         def build
@@ -40,13 +42,8 @@ module GrapeOAS
         end
 
         def build_schema_or_ref(schema)
-          if schema.respond_to?(:canonical_name) && schema.canonical_name
-            @ref_tracker << schema.canonical_name if @ref_tracker
-            ref_name = schema.canonical_name.gsub("::", "_")
-            { "$ref" => "#/components/schemas/#{ref_name}" }
-          else
-            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
-          end
+          @schema_builder.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy)
+                         .build_schema_or_ref(schema)
         end
       end
     end

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

@@ -4,10 +4,12 @@ module GrapeOAS
   module Exporter
     module OAS3
       class Response
-        def initialize(responses, ref_tracker = nil, nullable_strategy: Constants::NullableStrategy::KEYWORD)
+        def initialize(responses, ref_tracker = nil, nullable_strategy: Constants::NullableStrategy::KEYWORD,
+                       schema_builder: Schema)
           @responses = responses
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @schema_builder = schema_builder
         end
 
         def build
@@ -42,7 +44,7 @@ module GrapeOAS
         end
 
         def build_content(media_types, response_examples = nil)
-          return nil unless media_types
+          return nil if media_types.nil? || media_types.empty?
 
           media_types.each_with_object({}) do |mt, h|
             entry = { "schema" => build_schema_or_ref(mt.schema) }
@@ -71,13 +73,8 @@ module GrapeOAS
         end
 
         def build_schema_or_ref(schema)
-          if schema.respond_to?(:canonical_name) && schema.canonical_name
-            @ref_tracker << schema.canonical_name if @ref_tracker
-            ref_name = schema.canonical_name.gsub("::", "_")
-            { "$ref" => "#/components/schemas/#{ref_name}" }
-          else
-            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
-          end
+          @schema_builder.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy)
+                         .build_schema_or_ref(schema)
         end
       end
     end