grape-oas 1.5.0 → 1.6.0

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

@@ -44,10 +44,18 @@ module GrapeOAS
         # @return [ApiModel::Schema] the built schema
         def schema_for_exposure(exposure, doc)
           opts = exposure_options(exposure)
-          type = opts[:using] || doc[:type]
+          nullable_type = Constants.nullable_type(doc[:types])
+          if opts[:using] && doc.key?(:types)
+            GrapeOAS.logger.warn("Ignoring types: because using: takes precedence")
+          elsif doc.key?(:types) && !nullable_type
+            GrapeOAS.logger.warn("Ignoring unsupported entity documentation types: #{doc[:types].inspect}")
+          end
 
+          type = opts[:using] || nullable_type || doc[:type]
           schema = type_resolver.build_exposure_base_schema(type)
-          schema = apply_exposure_properties(schema, doc)
+          schema = apply_exposure_properties(
+            schema, doc, inferred_nullable: !nullable_type.nil? && !opts[:using],
+          )
           SchemaConstraints.apply(schema, doc)
           schema
         end
@@ -110,7 +118,8 @@ module GrapeOAS
 
         # Determines whether a property should be marked required.
         # Explicit doc[:required] takes precedence; conditional exposures
-        # default to false; unconditional exposures default to true.
+        # default to false; unconditional exposures fall back to
+        # GrapeOAS.entity_exposure_required_default (default `true`).
         #
         # @param doc [Hash] normalized documentation hash
         # @param exposure the entity exposure
@@ -119,7 +128,7 @@ module GrapeOAS
           return doc[:required] unless doc[:required].nil?
           return false if conditional?(exposure)
 
-          true
+          GrapeOAS.entity_exposure_required_default
         end
 
         private
@@ -159,10 +168,28 @@ module GrapeOAS
           return prop_schema unless is_array
 
           array_schema = ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: prop_schema)
+          if PropertyExtractor.extract_nullable(doc)
+            array_schema.nullable = true
+            if bare_single_ref_allof?(prop_schema)
+              array_schema.items = prop_schema.all_of.first
+            else
+              prop_schema.nullable = false
+            end
+          end
           array_schema.examples = doc[:example] if array_valued_example?(doc)
           array_schema
         end
 
+        def bare_single_ref_allof?(schema)
+          return false unless schema.all_of&.one? && schema.all_of.first.canonical_name
+
+          empty_schema = ApiModel::Schema.new
+          # Comparing defaults keeps future schema attributes from being discarded.
+          (ApiModel::Schema::VALID_ATTRIBUTES - %i[nullable all_of]).all? do |attribute|
+            schema.public_send(attribute) == empty_schema.public_send(attribute)
+          end
+        end
+
         # Detects block-based nesting exposures (NestingExposure) that should become
         # inline object schemas. Only triggers when no entity class is via `using:`.
         def nesting_exposure?(exposure)
@@ -206,8 +233,15 @@ module GrapeOAS
           schema
         end
 
-        def apply_exposure_properties(schema, doc)
-          nullable = PropertyExtractor.extract_nullable(doc)
+        def apply_exposure_properties(schema, doc, inferred_nullable: false)
+          schema = schema.dup if inferred_nullable && !schema.canonical_name
+          nullable_false = doc[:nullable] == false ||
+                           (doc[:x].is_a?(Hash) && doc[:x][:nullable] == false)
+          nullable = if (schema.nullable || inferred_nullable) && nullable_false
+                       false
+                     else
+                       schema.nullable || inferred_nullable || PropertyExtractor.extract_nullable(doc)
+                     end
           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 }] }.

data/lib/grape_oas/type_resolvers/array_resolver.rb

@@ -58,17 +58,19 @@ module GrapeOAS
         end
 
         def build_items_schema(type_names)
-          if nullable_type_pair?(type_names)
-            schema = build_items_for_name(type_names.find { |name| !nil_type_name?(name) })
+          if (nullable_type = Constants.nullable_type(type_names))
+            schema = build_items_for_name(nullable_type)
             schema.nullable = true
             return schema
           end
 
           return build_items_for_name(type_names.first) if type_names.size == 1
 
-          has_nil_type = type_names.any? { |name| nil_type_name?(name) }
-          variants = type_names.reject { |name| nil_type_name?(name) }.map { |name| build_items_for_name(name) }
-          ApiModel::Schema.new(one_of: variants, nullable: has_nil_type ? true : nil)
+          nil_types, other_types = type_names.partition { |type| Constants.nil_type?(type) }
+          variants = other_types.map { |type| build_items_for_name(type) }
+          schema = ApiModel::Schema.new(one_of: variants)
+          schema.nullable = true if nil_types.any?
+          schema
         end
 
         def build_items_for_name(type_name)
@@ -80,15 +82,6 @@ module GrapeOAS
           end
         end
 
-        def nullable_type_pair?(type_names)
-          type_names.size == 2 && type_names.one? { |name| nil_type_name?(name) }
-        end
-
-        def nil_type_name?(type_name)
-          normalized = type_name.to_s
-          normalized == "NilClass" || normalized == "Nil" || normalized.end_with?("::Nil")
-        end
-
         def build_schema_from_class(klass)
           # First, check if Introspectors can handle this class
           # (e.g., Grape::Entity, Dry::Schema, custom types)

data/lib/grape_oas/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeOAS
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/lib/grape_oas.rb

@@ -91,6 +91,25 @@ module GrapeOAS
 
   module_function :logger, :logger=
 
+  # @return [Boolean] whether entity exposures without required metadata
+  #   default to required
+  def entity_exposure_required_default
+    return true if @entity_exposure_required_default.nil?
+
+    @entity_exposure_required_default
+  end
+
+  # @param value [true, false, nil] `nil` resets to the default (`true`)
+  def entity_exposure_required_default=(value)
+    unless value.nil? || value == true || value == false
+      raise ArgumentError, "entity_exposure_required_default must be true, false, or nil (got #{value.class})"
+    end
+
+    @entity_exposure_required_default = value
+  end
+
+  module_function :entity_exposure_required_default, :entity_exposure_required_default=
+
   # Returns the global introspector registry.
   #
   # The registry manages introspectors that build schemas from various sources

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-oas
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Andrei Subbota
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -86,6 +86,7 @@ files:
 - lib/grape_oas/exporter.rb
 - lib/grape_oas/exporter/base/operation.rb
 - lib/grape_oas/exporter/base/paths.rb
+- lib/grape_oas/exporter/concerns/enum_normalizer.rb
 - lib/grape_oas/exporter/concerns/schema_indexer.rb
 - lib/grape_oas/exporter/concerns/tag_builder.rb
 - lib/grape_oas/exporter/oas2/operation.rb