grape-oas 1.5.0 → 1.6.0

data/lib/grape_oas/api_model_builders/response_parsers/http_codes_parser.rb

@@ -3,20 +3,31 @@
 module GrapeOAS
   module ApiModelBuilders
     module ResponseParsers
-      # Parser for responses defined via :http_codes, :failure, or :success options
-      # These are legacy grape-swagger formats that we support for compatibility
+      # Parser for responses defined via :http_codes, :failure, :success, or
+      # :default / :default_response (the OAS "default" catch-all).
       class HttpCodesParser
         include Base
 
+        DEFAULT_RESPONSE_MESSAGE = "Default Response"
+        DEFAULT_RESPONSE_CODE = "default"
+
         def applicable?(route)
           options_applicable?(route) || desc_block?(route)
         end
 
         def parse(route)
           specs = parse_from_options(route)
-          return specs unless specs.empty?
+          specs = parse_from_desc(route) if specs.empty?
+          return specs if specs.any? { |spec| spec[:code].to_s == DEFAULT_RESPONSE_CODE }
+
+          specs + default_response_specs(route)
+        end
 
-          parse_from_desc(route)
+        def default_response_specs(route)
+          data = route.options
+          value = default_response_value(data)
+          value ||= default_response_value(desc_data(route))
+          value ? parse_default_response(value, route) : []
         end
 
         private
@@ -46,15 +57,65 @@ module GrapeOAS
         def parse_values(data, route)
           return [] unless data.is_a?(Hash)
 
-          %i[http_codes failure success].flat_map do |key|
-            parse_value(data[key], route)
+          specs = %i[http_codes failure success].flat_map do |key|
+            parse_value(data[key], route, success: key == :success)
+          end
+          default_value = data[:default_response] || data[:default]
+          return specs unless default_value
+
+          specs.reject { |spec| spec[:code].to_s == DEFAULT_RESPONSE_CODE } +
+            parse_default_response(default_value, route)
+        end
+
+        # Grape 3.x stores `desc { default ... }` as :default. Grape 4.0
+        # (ruby-grape/grape#2861) renamed that key to :default_response and
+        # remaps the deprecated `default` alias at write time. Always emit the
+        # OAS "default" status — grape-swagger ignores a numeric `code:` here.
+        def parse_default_response(value, route)
+          entries_for(value).map { |entry| normalize_default_response_entry(entry, route) }
+        end
+
+        def normalize_default_response_entry(entry, route)
+          if entry.is_a?(Hash)
+            entry = normalize_hash_keys(entry)
+            {
+              code: DEFAULT_RESPONSE_CODE,
+              message: extract_description(entry) || DEFAULT_RESPONSE_MESSAGE,
+              entity: extract_entity(entry, nil),
+              headers: entry[:headers],
+              examples: entry[:examples],
+              as: entry[:as],
+              one_of: normalize_one_of(entry[:one_of]),
+              is_array: entry.key?(:is_array) ? entry[:is_array] : route.options[:is_array],
+              required: entry[:required]
+            }
+          else
+            {
+              code: DEFAULT_RESPONSE_CODE,
+              message: DEFAULT_RESPONSE_MESSAGE,
+              entity: entry,
+              headers: nil,
+              is_array: route.options[:is_array]
+            }
           end
         end
 
-        def parse_value(value, route)
+        def default_response_value(data)
+          return unless data.is_a?(Hash)
+
+          data[:default_response] || data[:default]
+        end
+
+        def normalize_one_of(one_of)
+          return one_of unless one_of.is_a?(Array)
+
+          one_of.map { |entry| normalize_hash_keys(entry) }
+        end
+
+        def parse_value(value, route, success:)
           return [] unless value
 
-          entries_for(value).map { |entry| normalize_entry(entry, route) }
+          entries_for(value).map { |entry| normalize_entry(entry, route, success: success) }
         end
 
         def entries_for(value)
@@ -73,12 +134,14 @@ module GrapeOAS
         def options_applicable?(route)
           entity_hash = route.options[:entity].is_a?(Hash) ? route.options[:entity] : nil
           route.options[:http_codes] || route.options[:failure] || route.options[:success] ||
+            route.options[:default] || route.options[:default_response] ||
             (entity_hash && (entity_hash[:code] || entity_hash[:model] || entity_hash[:entity] || entity_hash[:one_of]))
         end
 
         def desc_block?(route)
           data = desc_data(route)
-          data && (data[:success] || data[:failure] || data[:http_codes] || data[:entity])
+          data && (data[:success] || data[:failure] || data[:http_codes] || data[:entity] ||
+            data[:default] || data[:default_response])
         end
 
         def desc_block_has_explicit_success?(route)
@@ -86,6 +149,9 @@ module GrapeOAS
         end
 
         def append_entity_spec(specs, entity_value, route)
+          explicit_code = (entity_value[:code] if entity_value.is_a?(Hash)) || route.options[:default_status]
+          return specs if !explicit_code && specs.any? { |spec| spec[:code] == "2XX" || (200..299).cover?(spec[:code].to_i) }
+
           entity_spec = build_entity_spec(entity_value, route)
           return specs if specs.any? { |spec| spec[:code].to_i == entity_spec[:code].to_i }
 
@@ -96,7 +162,7 @@ module GrapeOAS
           if entity_value.is_a?(Hash)
             # Hash format: { code: 201, model: Entity, message: "Created" }
             {
-              code: entity_value[:code] || 200,
+              code: entity_value[:code] || default_response_code(route, success: true),
               message: entity_value[:message],
               entity: extract_entity(entity_value, nil),
               headers: entity_value[:headers],
@@ -109,7 +175,7 @@ module GrapeOAS
           else
             # Plain entity class
             {
-              code: 200,
+              code: default_response_code(route, success: true),
               message: nil,
               entity: entity_value,
               headers: nil,
@@ -121,24 +187,26 @@ module GrapeOAS
           end
         end
 
-        def normalize_entry(entry, route)
-          case entry
-          when Hash
-            normalize_hash_entry(entry, route)
-          when Array
-            normalize_array_entry(entry, route)
-          when Class, Module
-            # Plain entity class (e.g., success TestEntity)
-            normalize_entity_entry(entry, route)
-          else
-            normalize_plain_entry(entry, route)
-          end
+        def normalize_entry(entry, route, success:)
+          spec = case entry
+                 when Hash
+                   normalize_hash_entry(entry, route, success: success)
+                 when Array
+                   normalize_array_entry(entry, route)
+                 when Class, Module
+                   # Plain entity class (e.g., success TestEntity)
+                   normalize_entity_entry(entry, route, success: success)
+                 else
+                   normalize_plain_entry(entry, route)
+                 end
+          spec[:code] = normalize_status_code(spec[:code])
+          spec
         end
 
-        def normalize_hash_entry(entry, route)
-          default_code = (route.options[:default_status] || 200).to_s
+        def normalize_hash_entry(entry, route, success:)
+          default_code = default_response_code(route, success: success)
           {
-            code: extract_status_code(entry, default_code),
+            code: extract_status_code(entry, default_code.to_s),
             message: extract_description(entry),
             entity: extract_entity(entry, route.options[:entity]),
             headers: entry[:headers],
@@ -163,10 +231,10 @@ module GrapeOAS
           }
         end
 
-        def normalize_entity_entry(entity_class, route)
+        def normalize_entity_entry(entity_class, route, success:)
           # Plain entity class (e.g., success TestEntity)
           {
-            code: route.options[:default_status] || 200,
+            code: default_response_code(route, success: success),
             message: nil,
             entity: entity_class,
             headers: nil,

data/lib/grape_oas/constants.rb

@@ -72,6 +72,20 @@ module GrapeOAS
       VARIANT_COLLECTION = /\A(?<container>Array|Set)\[(?<inner>#{CONST_NAME}(?:,\s*#{CONST_NAME})+)\]\z/
     end
 
+    def self.nil_type?(type)
+      return true if type.nil?
+
+      name = type.to_s
+      name == "NilClass" || name == "Nil" || name.end_with?("::Nil")
+    end
+
+    def self.nullable_type(types)
+      return unless types.is_a?(Array) && types.size == 2
+
+      nil_types, other_types = types.partition { |type| nil_type?(type) }
+      other_types.first if nil_types.size == 1
+    end
+
     # Default values for OpenAPI spec when not provided by user
     module Defaults
       LICENSE_NAME = "Proprietary"

data/lib/grape_oas/exporter/concerns/enum_normalizer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module Concerns
+      module EnumNormalizer
+        private
+
+        def normalize_enum(enum_values, type, preserve_nil: false)
+          return nil unless enum_values.is_a?(Array)
+
+          base_type = base_type_for(type)
+          normalized = enum_values.each_with_object([]) do |value, values|
+            next if value.nil?
+
+            normalized_value = case base_type
+                               when Constants::SchemaTypes::INTEGER then value.to_i if value.respond_to?(:to_i)
+                               when Constants::SchemaTypes::NUMBER then value.to_f if value.respond_to?(:to_f)
+                               else value
+                               end
+            values << normalized_value unless normalized_value.nil?
+          end
+
+          normalized.uniq!
+          normalized << nil if preserve_nil && enum_values.include?(nil)
+          normalized unless normalized.empty?
+        end
+
+        def base_type_for(type)
+          type.is_a?(Array) ? (type - [Constants::SchemaTypes::NULL]).first : type
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter/concerns/schema_indexer.rb

@@ -7,13 +7,30 @@ module GrapeOAS
       # Handles building schema indexes from operations and collecting nested schema references.
       module SchemaIndexer
         def find_schema_by_canonical_name(canonical_name)
-          @ref_schemas[canonical_name] || schema_index[canonical_name]
+          schema = @ref_schemas[canonical_name] || schema_index[canonical_name]
+          ensure_unique_schema_ref_name!(canonical_name) if schema
+          schema
         end
 
         def schema_index
           @schema_index ||= build_schema_index
         end
 
+        def ensure_unique_schema_ref_name!(canonical_name)
+          ref_name = GrapeOAS.schema_ref_name.call(canonical_name)
+          canonical_names_by_ref = @canonical_names_by_ref ||= {}
+          existing_name = canonical_names_by_ref[ref_name]
+
+          if existing_name && existing_name != canonical_name
+            raise ArgumentError,
+                  "Schema reference name #{ref_name.inspect} is generated for both " \
+                  "#{existing_name.inspect} and #{canonical_name.inspect}; " \
+                  "configure GrapeOAS.schema_ref_name to generate unique names"
+          end
+
+          canonical_names_by_ref[ref_name] = canonical_name
+        end
+
         def build_schema_index
           index = {}
           # Index schemas from operations

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

@@ -4,6 +4,8 @@ module GrapeOAS
   module Exporter
     module OAS2
       class Parameter
+        include Concerns::EnumNormalizer
+
         PRIMITIVE_MAPPINGS = {
           Constants::SchemaTypes::INTEGER => { type: Constants::SchemaTypes::INTEGER },
           "long" => { type: Constants::SchemaTypes::INTEGER, format: "int64" },
@@ -28,7 +30,7 @@ module GrapeOAS
         FORM_MEDIA_TYPES = %w[application/x-www-form-urlencoded multipart/form-data].freeze
 
         def build
-          params = Array(@op.parameters).map { |param| build_parameter(param) }
+          params = representable_parameters.map { |param| build_parameter(param) }
           if @op.request_body
             if form_only_request?
               params.concat(build_form_parameters(@op.request_body))
@@ -41,10 +43,53 @@ module GrapeOAS
 
         private
 
+        # Swagger 2.0 restricts `in` to query|header|path|formData|body and
+        # non-body parameters to primitive types or arrays of primitives.
+        # Drop unsupported parameters rather than emit an invalid document,
+        # since ParamLocationResolver resolves per-parameter without knowing
+        # the target OAS version.
+        def representable_parameters
+          Array(@op.parameters).reject do |param|
+            if param.location == "cookie"
+              GrapeOAS.logger.warn("Dropping cookie parameter '#{param.name}': not representable in OAS 2.0")
+              true
+            elsif param.location != "body" &&
+                  unrepresentable?(param.schema, location: param.location)
+              GrapeOAS.logger.warn(
+                "Dropping parameter '#{param.name}': schema is not representable as an " \
+                "OAS 2.0 #{param.location} parameter",
+              )
+              true
+            else
+              false
+            end
+          end
+        end
+
+        def first_alternative_schema(schema)
+          return schema if schema.nil? || schema.type
+          return schema if schema.all_of&.any?
+          return first_alternative_schema(schema.one_of.first) if schema.one_of&.any?
+          return first_alternative_schema(schema.any_of.first) if schema.any_of&.any?
+
+          schema
+        end
+
+        def unrepresentable?(schema, location:, array_item: false)
+          schema = first_alternative_schema(schema)
+          return true unless schema&.type
+          return true if schema.all_of&.any?
+          return unrepresentable?(schema.items, location: location, array_item: true) if schema.type == Constants::SchemaTypes::ARRAY
+          return true if schema.type == Constants::SchemaTypes::OBJECT
+
+          schema.type == Constants::SchemaTypes::FILE && (location != "formData" || array_item)
+        end
+
         def build_parameter(param)
-          type = param.schema&.type
-          format = param.schema&.format
-          primitive_types = PRIMITIVE_MAPPINGS.keys + %w[object string boolean file json array number]
+          schema = param.location == "body" ? param.schema : first_alternative_schema(param.schema)
+          type = schema&.type
+          format = schema&.format
+          primitive_types = PRIMITIVE_MAPPINGS.keys + %w[string boolean file json array number]
           is_primitive = type && primitive_types.include?(type)
 
           if is_primitive && param.location != "body"
@@ -57,8 +102,8 @@ module GrapeOAS
               "type" => mapping ? mapping[:type] : type,
               "format" => format || (mapping ? mapping[:format] : nil)
             }
-            apply_schema_constraints(result, param.schema)
-            apply_collection_format(result, param, type)
+            apply_schema_constraints(result, schema)
+            apply_collection_format(result, param, schema)
             result.compact
           else
             {
@@ -66,7 +111,7 @@ module GrapeOAS
               "in" => param.location,
               "required" => param.required,
               "description" => param.description,
-              "schema" => build_schema_or_ref(param.schema)
+              "schema" => build_schema_or_ref(schema)
             }.tap do |h|
               h["type"] = type if type
               h["format"] = format if format
@@ -91,30 +136,10 @@ module GrapeOAS
           result["default"] = schema.default if schema.respond_to?(:default) && !schema.default.nil?
         end
 
-        def normalize_enum(enum_vals, type)
-          return nil unless enum_vals.is_a?(Array)
-
-          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!
-          return nil if result.empty?
-
-          result
-        end
-
-        def apply_collection_format(result, param, type)
-          return unless type == Constants::SchemaTypes::ARRAY
+        def apply_collection_format(result, param, schema)
+          return unless schema.type == Constants::SchemaTypes::ARRAY
 
-          result["items"] = build_schema_or_ref(param.schema.items) if param.schema.items
+          result["items"] = build_schema_or_ref(schema.items) if schema.items
           return unless param.collection_format
 
           valid_formats = %w[csv ssv tsv pipes multi brackets]

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

@@ -4,6 +4,8 @@ module GrapeOAS
   module Exporter
     module OAS2
       class Schema
+        include Concerns::EnumNormalizer
+
         def initialize(schema, ref_tracker = nil, nullable_strategy: nil, composition_extensions: false)
           @schema = schema
           @ref_tracker = ref_tracker
@@ -38,7 +40,7 @@ module GrapeOAS
             "description" => @schema.description&.to_s,
             "properties" => build_properties(@schema.properties)
           }
-          schema_hash["enum"] = normalize_enum(@schema.enum, @schema.type, nullable: nullable?) if @schema.enum
+          schema_hash["enum"] = normalize_enum(@schema.enum, @schema.type, preserve_nil: enum_allows_null?(@schema)) 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
@@ -99,6 +101,10 @@ module GrapeOAS
           schema_nullable?(@schema)
         end
 
+        def enum_allows_null?(schema)
+          @nullable_strategy == Constants::NullableStrategy::EXTENSION && schema_nullable?(schema)
+        end
+
         # OAS2 keeps a first-alternative fallback for tools that ignore extensions.
         def build_first_of_schema(composition_type)
           schemas = composition_type == :any_of ? @schema.any_of : @schema.one_of
@@ -130,7 +136,7 @@ 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, @schema.type, nullable: nullable?) if @schema.enum
+          result["enum"] = normalize_enum(@schema.enum, @schema.type, preserve_nil: enum_allows_null?(@schema)) if @schema.enum
           result.delete("enum") if result.key?("enum") && result["enum"].nil?
           apply_constraints(result)
           apply_extensions(result)
@@ -156,7 +162,7 @@ module GrapeOAS
             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["enum"] = normalize_enum(schema.enum, schema.type, preserve_nil: enum_allows_null?(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
@@ -175,29 +181,6 @@ module GrapeOAS
             built
           end
         end
-
-        def normalize_enum(enum_vals, type, nullable: false)
-          return nil unless enum_vals.is_a?(Array)
-
-          has_nil = nullable && enum_vals.include?(nil)
-
-          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
   end

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

@@ -4,6 +4,8 @@ module GrapeOAS
   module Exporter
     module OAS3
       class Schema
+        include Concerns::EnumNormalizer
+
         def initialize(schema, ref_tracker = nil, nullable_strategy: Constants::NullableStrategy::KEYWORD)
           @schema = schema
           @ref_tracker = ref_tracker
@@ -41,7 +43,11 @@ module GrapeOAS
 
           end
           schema_hash["required"] = @schema.required if @schema.required && !@schema.required.empty?
-          schema_hash["enum"] = normalize_enum(@schema.enum, schema_hash["type"], nullable: nullable?) if @schema.enum
+          if @schema.enum
+            schema_hash["enum"] = normalize_enum(
+              @schema.enum, schema_hash["type"], preserve_nil: enum_allows_null?(@schema, schema_hash["type"]),
+            )
+          end
           schema_hash["default"] = @schema.default unless @schema.default.nil?
           schema_hash
         end
@@ -88,7 +94,11 @@ module GrapeOAS
             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
+            if schema.enum
+              result["enum"] = normalize_enum(
+                schema.enum, enum_type, preserve_nil: enum_allows_null?(schema, enum_type, null_union: true),
+              )
+            end
             sanitize_enum_against_type(result, type: schema.type)
             apply_all_constraints(result, schema)
             result.merge!(schema.extensions) if schema.extensions
@@ -110,12 +120,6 @@ module GrapeOAS
 
         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!`.
@@ -170,7 +174,11 @@ 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"], nullable: nullable?) if @schema.enum
+          if @schema.enum
+            result["enum"] = normalize_enum(
+              @schema.enum, result["type"], preserve_nil: enum_allows_null?(@schema, result["type"], null_union: true),
+            )
+          end
           sanitize_enum_against_type(result)
           apply_all_constraints(result)
           apply_composition_extensions(result)
@@ -305,38 +313,17 @@ module GrapeOAS
           { "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)
-
-          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)
+        def enum_allows_null?(schema, type, null_union: false)
+          has_null_type = type.is_a?(Array) && type.include?(Constants::SchemaTypes::NULL)
 
-          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?
+          case @nullable_strategy
+          when Constants::NullableStrategy::KEYWORD
+            has_null_type || (schema_nullable?(schema) && (!type.nil? || null_union))
+          when Constants::NullableStrategy::TYPE_ARRAY
+            has_null_type || (schema_nullable?(schema) && null_union)
+          else
+            false
           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)