grape-oas 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0520e8f719a37c5e33b330a681a9e8da8b1c3a9b921aa245ef328d716bf2bd9
-  data.tar.gz: aa612915b60e40933256692bb9ad33b2dcf77bc1f68c52d2a9c32cd0befc0bff
+  metadata.gz: d956b648ef9686c13b90db7a16bba4038bf505ed069634131ade6cac17b3f8bf
+  data.tar.gz: 740148b7d4a9cb0d09675d53465a6e4b798b5c042245070b7de145401ac47820
 SHA512:
-  metadata.gz: 312f2f0c9dfae0735187b4b7e6ab1969c619e36d58b74e094d990354fdc827a809b49a2ab7ec910bb1e67ac586b9fa4da54742b2f2cd449cca289832e88e5ae3
-  data.tar.gz: 0e94d7856bc9e94c354b56196f8a77a1689f17281298dc56810de7792fc4d91988fe38f4943a98c9dbf855dae644a36ca01df376a3176210c6d1ef5764ff1db0
+  metadata.gz: a9e134fc9ad362b0b2aa505d7dcab8b24cf35697356365fda1d0bc20f081893b675811b2205aca46507aeb6da66ea547cee8bb3a01a5c6de301f097bb7990948
+  data.tar.gz: 3a2c13601c299600272d5ff3e5cccb648f658b61b0a3d1a8cf43c66b0bb35cadae8979f74bffd820ec217ccbd18e8eb65b25c28de9f6b4b67a1972914b524f92

data/CHANGELOG.md

@@ -2,22 +2,48 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-01-23
 
+### Added
+
+- [#30](https://github.com/numbata/grape-oas/pull/30): Add support for Grape's native `contract` DSL resolution when building request schemas - [@numbata](https://github.com/numbata).
+- [#28](https://github.com/numbata/grape-oas/pull/28): support nested dry-contracts query parameters with style & explode - [@slbug](https://github.com/slbug).
+- [#24](https://github.com/numbata/grape-oas/pull/24): Properly parse desc blocks with responses [@slbug](https://github.com/slbug).
+- [#27](https://github.com/numbata/grape-oas/pull/27): Add release workflow - [@numbata](https://github.com/numbata).
+- [#26](https://github.com/numbata/grape-oas/pull/26): Add danger validation - [@numbata](https://github.com/numbata).
+- [#23](https://github.com/numbata/grape-oas/pull/23): Add oneOf support for response schemas - [@slbug](https://github.com/slbug).
+
+### Fixed
+
+- [#33](https://github.com/numbata/grape-oas/pull/33): Improve schema generation: add format hints, optimize nullable types, fix enum handling for arrays and oneOf - [@numbata](https://github.com/numbata).
+- [#34](https://github.com/numbata/grape-oas/pull/34): Convert numeric `included_in?` ranges to min/max constraints instead of enum - [@numbata](https://github.com/numbata).
+- [#31](https://github.com/numbata/grape-oas/pull/31): Fix: prefer `using:` option over `documentation: { type: "object" }` - [@numbata](https://github.com/numbata).
+- [#22](https://github.com/numbata/grape-oas/pull/22): Handle boolean types in dry introspector - [@slbug](https://github.com/slbug).
+
+## [1.0.3] - 2025-12-23
+
+### Fixed
+
+- [#21](https://github.com/numbata/grape-oas/pull/21): Remove unnecessary require\_relative in favor of Zeitwerk autoloadin - [@numbata](https://github.com/numbata).
+- [#17](https://github.com/numbata/grape-oas/pull/17): Support for nested rules and predicates in dry-schema introspection - [@slbug](https://github.com/slbug).
+- [#20](https://github.com/numbata/grape-oas/pull/20): Use annotation for coverage report - [@numbata](https://github.com/numbata).
+- [#18](https://github.com/numbata/grape-oas/pull/18): Support for range in size? predicate `required(:tags).value(:array, size?: 1..10).each(:string)` - [@slbug](https://github.com/slbug).
+- [#19](https://github.com/numbata/grape-oas/pull/19): Temporary disable memory profiler workflow for PRs - [@numbata](https://github.com/numbata).
 
 ## [1.0.2] - 2025-12-15
 
-### Fixes
+### Fixed
 
 - [#14](https://github.com/numbata/grape-oas/pull/14): Fix Response and ParamSchemaBuilder to use introspector registry instead of directly instantiating EntityIntrospector - [@numbata](https://github.com/numbata).
 
 ## [1.0.1] - 2025-12-15
 
-### Fixes
+### Fixed
 
-- [#8](https://github.com/numbata/grape-oas/pull/8): Add OAS2 parameter schema constraint export with enum normalization and retain zero-valued constraints across OAS exporters. - [@numbata](https://github.com/numbata).
+- [#8](https://github.com/numbata/grape-oas/pull/8): Add OAS2 parameter schema constraint export with enum normalization and retain zero-valued constraints across OAS exporters - [@numbata](https://github.com/numbata).
 - [#9](https://github.com/numbata/grape-oas/pull/9): Treat GET/HEAD/DELETE as bodyless by default via shared constants and tests - [@numbata](https://github.com/numbata).
 - [#10](https://github.com/numbata/grape-oas/pull/10): Add grape-swagger compatible `in:` location syntax for parameters alongside `param_type` - [@numbata](https://github.com/numbata).
 - [#11](https://github.com/numbata/grape-oas/pull/11): Flatten nested Hash params to bracket-notation query params for GET/HEAD/DELETE requests - [@numbata](https://github.com/numbata).
@@ -27,74 +53,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-#### Core Features
-- OpenAPI specification generation for Grape APIs
-- Support for OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications
-- `GrapeOAS.generate(app:, schema_type:)` for programmatic generation
-- `add_oas_documentation` DSL for mounting documentation endpoint
-- `add_swagger_documentation` compatibility shim for grape-swagger migration
-- Query parameter `?oas=2|3|3.1` for version selection at runtime
-
-#### Entity Support
-- Built-in Grape::Entity introspection (no separate gem needed)
-- Dry::Validation::Contract and Dry::Struct support
-- Entity inheritance with `allOf` composition
-- Polymorphism support with `discriminator`
-- Sum types (`|`) converted to `anyOf`
-- Circular reference handling with `$ref`
-
-#### Parameter Documentation
-- All Grape parameter types (String, Integer, Float, Boolean, Date, DateTime, Array, Hash, File)
-- Nested parameters (Hash with block)
-- Array parameters with item types (`Array[String]`, `Array[Integer]`)
-- Multi-type parameters (`types: [String, Integer]`)
-- Parameter validation constraints (values, regexp, minimum, maximum, etc.)
-- Parameter hiding (`documentation: { hidden: true }`)
-- `collectionFormat` support for OAS2 arrays
-
-#### Response Documentation
-- `success` and `failure` response definitions
-- Multiple success/failure status codes
-- Response headers
-- Response examples
-- Multiple present responses with `as:` key combination
-- Root element wrapping support
-- `suppress_default_error_response` option
-
-#### Endpoint Documentation
-- `desc` block syntax with detail, tags, deprecated, consumes, produces
-- Endpoint hiding (`hidden: true` or lambda)
-- `body_name` for custom body parameter naming (OAS2)
-- Request body for GET/HEAD/DELETE when explicitly enabled
-- Operation extensions (`x-*` properties)
-
-#### Configuration
-- Global options: host, base_path, schemes, servers, consumes, produces
-- Info object: title, version, description, contact, license, terms_of_service
-- Security definitions (API key, OAuth2, Bearer)
-- Tag definitions with descriptions
-- `models` option to pre-register entities
-- Namespace filtering for partial schema generation
-- URL-based namespace filtering for mounted docs (`/swagger_doc/users`)
-- Tag filtering to only include used tags
-
-#### Rake Tasks
-- `grape_oas:generate[API,schema_type,output_path]` for file generation
-- `grape_oas:validate[file_path]` for spec validation
-
-#### Migration Support
-- Comprehensive migration guide from grape-swagger
-- Feature parity documentation
-- Compatibility shim for `add_swagger_documentation`
-
-#### Extensibility
-- Introspector registry - register custom introspectors via `GrapeOAS.introspectors.register()`
-- Exporter registry - register custom exporters via `GrapeOAS.exporters.register(ExporterClass, as: :alias)`
-
-### Documentation
-- README with full usage examples
-- `docs/MIGRATING_FROM_GRAPE_SWAGGER.md` - detailed migration guide
-- `docs/ARCHITECTURE.md` - system architecture overview
-- `docs/INTROSPECTORS.md` - introspector system documentation
-- `docs/EXPORTERS.md` - exporter system documentation
-- `docs/API_MODEL.md` - internal API model reference
+- Core Features
+  - OpenAPI specification generation for Grape APIs
+  - Support for OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications
+  - `GrapeOAS.generate(app:, schema_type:)` for programmatic generation
+  - `add_oas_documentation` DSL for mounting documentation endpoint
+  - `add_swagger_documentation` compatibility shim for grape-swagger migration
+  - Query parameter `?oas=2|3|3.1` for version selection at runtime
+-  Entity Support
+  - Built-in Grape::Entity introspection (no separate gem needed)
+  - Dry::Validation::Contract and Dry::Struct support
+  - Entity inheritance with `allOf` composition
+  - Polymorphism support with `discriminator`
+  - Sum types (`|`) converted to `anyOf`
+  - Circular reference handling with `$ref`
+-  Parameter Documentation
+  - All Grape parameter types (String, Integer, Float, Boolean, Date, DateTime, Array, Hash, File)
+  - Nested parameters (Hash with block)
+  - Array parameters with item types (`Array[String]`, `Array[Integer]`)
+  - Multi-type parameters (`types: [String, Integer]`)
+  - Parameter validation constraints (values, regexp, minimum, maximum, etc.)
+  - Parameter hiding (`documentation: { hidden: true }`)
+  - `collectionFormat` support for OAS2 arrays
+-  Response Documentation
+  - `success` and `failure` response definitions
+  - Multiple success/failure status codes
+  - Response headers
+  - Response examples
+  - Multiple present responses with `as:` key combination
+  - Root element wrapping support
+  - `suppress_default_error_response` option
+-  Endpoint Documentation
+  - `desc` block syntax with detail, tags, deprecated, consumes, produces
+  - Endpoint hiding (`hidden: true` or lambda)
+  - `body_name` for custom body parameter naming (OAS2)
+  - Request body for GET/HEAD/DELETE when explicitly enabled
+  - Operation extensions (`x-*` properties)
+-  Configuration
+  - Global options: host, base\_path, schemes, servers, consumes, produces
+  - Info object: title, version, description, contact, license, terms\_of\_service
+  - Security definitions (API key, OAuth2, Bearer)
+  - Tag definitions with descriptions
+  - `models` option to pre-register entities
+  - Namespace filtering for partial schema generation
+  - URL-based namespace filtering for mounted docs (`/swagger_doc/users`)
+  - Tag filtering to only include used tags
+-  Rake Tasks
+  - `grape_oas:generate[API,schema_type,output_path]` for file generation
+  - `grape_oas:validate[file_path]` for spec validation
+- Migration Support
+  - Comprehensive migration guide from grape-swagger
+  - Feature parity documentation
+  - Compatibility shim for `add_swagger_documentation`
+-  Extensibility
+  - Introspector registry - register custom introspectors via `GrapeOAS.introspectors.register()`
+  - Exporter registry - register custom exporters via `GrapeOAS.exporters.register(ExporterClass, as: :alias)`
+- Documentation
+  - README with full usage examples
+  - `docs/MIGRATING_FROM_GRAPE_SWAGGER.md` - detailed migration guide
+  - `docs/ARCHITECTURE.md` - system architecture overview
+  - `docs/INTROSPECTORS.md` - introspector system documentation
+  - `docs/EXPORTERS.md` - exporter system documentation
+  - `docs/API_MODEL.md` - internal API model reference

data/README.md

@@ -5,6 +5,30 @@
 
 OpenAPI Specification (OAS) documentation generator for [Grape](https://github.com/ruby-grape/grape) APIs. Supports OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications.
 
+## Table of Contents
+
+- [Why Grape::OAS?](#why-grapeoas)
+- [Features](#features)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Mount Documentation Endpoint](#mount-documentation-endpoint)
+  - [Manual Generation](#manual-generation)
+  - [Rake Tasks](#rake-tasks)
+- [Documentation](#documentation)
+- [Basic Usage](#basic-usage)
+  - [Documenting Endpoints](#documenting-endpoints)
+  - [Response Documentation](#response-documentation)
+  - [Entity Definition](#entity-definition)
+- [Extensibility](#extensibility)
+  - [Custom Introspectors](#custom-introspectors)
+  - [Custom Exporters](#custom-exporters)
+- [Related Projects](#related-projects)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+
 ## Why Grape::OAS?
 
 Grape::OAS is built around a **DTO (Data Transfer Object) architecture** that separates collecting API metadata from generating schemas. This clean separation makes the codebase easier to reason about and enables support for multiple output formats (OAS 2.0, 3.0, 3.1) from the same API definition.
@@ -164,7 +188,7 @@ schema = GrapeOAS.generate(app: API, schema_type: :custom)
 | [grape-entity](https://github.com/ruby-grape/grape-entity) | Entity exposure for Grape APIs |
 | [grape-swagger](https://github.com/ruby-grape/grape-swagger) | OpenAPI documentation for Grape APIs |
 | [grape-swagger-entity](https://github.com/ruby-grape/grape-swagger-entity) | grape-swagger adapter for grape-entity |
-| [oas_grape](https://github.com/a-chacon/oas_grape) | Another OpenAPI 3.1 generator for Grape |
+| [oas\_grape](https://github.com/a-chacon/oas_grape) | Another OpenAPI 3.1 generator for Grape |
 
 ## Development
 

data/lib/grape_oas/api_model/parameter.rb

@@ -8,9 +8,10 @@ module GrapeOAS
     # @see https://swagger.io/specification/
     # @see GrapeOAS::ApiModel::Operation
     class Parameter < Node
-      attr_accessor :location, :name, :required, :description, :schema, :collection_format
+      attr_accessor :location, :name, :required, :description, :schema, :collection_format, :style, :explode
 
-      def initialize(location:, name:, schema:, required: false, description: nil, collection_format: nil)
+      def initialize(location:, name:, schema:, required: false, description: nil, collection_format: nil, style: nil,
+                     explode: nil)
         super()
         @location = location.to_s
         @name = name
@@ -18,6 +19,8 @@ module GrapeOAS
         @schema = schema
         @description = description
         @collection_format = collection_format
+        @style = style&.to_s
+        @explode = explode
       end
     end
   end

data/lib/grape_oas/api_model_builders/concerns/type_resolver.rb

@@ -41,7 +41,7 @@ module GrapeOAS
           return Constants::SchemaTypes::ARRAY if type_str.match?(TYPED_ARRAY_PATTERN)
 
           # Handle string/symbol type names
-          Constants::PRIMITIVE_TYPE_MAPPING.fetch(type_str.downcase, Constants::SchemaTypes::STRING)
+          Constants.primitive_type(type_str) || Constants::SchemaTypes::STRING
         end
 
         # Checks if type is Grape's Boolean class (handles dynamic loading)
@@ -102,7 +102,10 @@ module GrapeOAS
           elsif primitive == Hash
             ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
           else
-            ApiModel::Schema.new(type: resolve_schema_type(primitive))
+            ApiModel::Schema.new(
+              type: resolve_schema_type(primitive),
+              format: Constants.format_for_type(primitive),
+            )
           end
         end
 

data/lib/grape_oas/api_model_builders/request.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "bigdecimal"
-require_relative "concerns/type_resolver"
 
 module GrapeOAS
   module ApiModelBuilders
@@ -24,7 +23,15 @@ module GrapeOAS
                                     .build
 
         contract_schema = build_contract_schema
-        body_schema = contract_schema if contract_schema
+
+        # For GET/HEAD/DELETE requests, convert contract schema to query parameters
+        # instead of putting it in request body, UNLESS request_body is explicitly enabled
+        if contract_schema && should_convert_contract_to_query_params?
+          contract_params = convert_contract_schema_to_params(contract_schema)
+          operation.add_parameters(*contract_params)
+        elsif contract_schema
+          body_schema = contract_schema
+        end
 
         operation.add_parameters(*route_params)
         append_request_body(body_schema) unless body_schema.empty?
@@ -46,12 +53,10 @@ module GrapeOAS
 
         # Set canonical_name if not already set (e.g., DryIntrospector may have set it for polymorphism)
         if body_schema.respond_to?(:canonical_name) && body_schema.canonical_name.nil?
-          settings = route.respond_to?(:settings) ? route.settings : {}
-          contract_class = route.options[:contract] || route.options[:schema] || settings[:contract]
+          contract = find_contract
 
-          if contract_class.is_a?(Class) && defined?(Menti::Endpoint::Schema) && contract_class < Menti::Endpoint::Schema
-            body_schema.canonical_name = contract_class.name
-          elsif contract_class # some other contract (e.g., Dry); keep inline
+          if contract
+            # Dry contracts are kept inline (no canonical_name)
             # no-op
           elsif body_schema.properties.values.any? { |prop| prop.respond_to?(:canonical_name) && prop.canonical_name }
             # keep entity/property refs intact; don't override
@@ -91,9 +96,64 @@ module GrapeOAS
         extract_extensions(mt)
       end
 
+      # Find contract from Grape's contract storage locations.
+      # Contracts can be defined in several ways:
+      # 1. Via `contract MyContract` DSL - stores in inheritable_setting.route[:saved_validations]
+      # 2. Via `desc "...", contract: MyContract` - stores in route.options[:contract]
+      # 3. Via `desc "...", schema: MySchema` - stores in route.options[:schema]
+      # 4. Via route.settings[:contract] - used by mounted APIs or legacy configuration
+      #
+      # @return [Object, nil] The contract instance or nil if not found
+      def find_contract
+        # Check route options first (from desc "...", contract: MyContract or schema: MySchema)
+        contract = route.options[:contract] || route.options[:schema]
+        return contract if contract
+
+        # Check route settings (mounted APIs or legacy configuration)
+        contract = route.settings[:contract] if route.respond_to?(:settings)
+        return contract if contract
+
+        # Check Grape's native contract() DSL storage
+        extract_contract_from_grape_validations
+      end
+
+      # Extract contract from Grape's native contract() DSL storage location.
+      # When using `contract MyContract` in Grape DSL, the contract is stored in
+      # route.app.inheritable_setting.route[:saved_validations] as validator options.
+      # This is a point-in-time copy specific to this endpoint, ensuring each route
+      # gets only its own contract even when multiple routes define different contracts.
+      #
+      # @return [Object, nil] The contract instance or nil if not found
+      def extract_contract_from_grape_validations
+        return unless route.respond_to?(:app) && route.app.respond_to?(:inheritable_setting)
+
+        setting = route.app.inheritable_setting
+        return unless setting.respond_to?(:route)
+
+        # Use route[:saved_validations] which contains only the validations
+        # for this specific endpoint (point-in-time copy), not the shared
+        # namespace_stackable[:validations] which contains all validators for the API class
+        validations = setting.route[:saved_validations]
+        return unless validations.is_a?(Array)
+
+        # Find ContractScopeValidator which holds the Dry contract/schema
+        contract_validation = validations.find do |v|
+          next unless v.is_a?(Hash)
+
+          validator_class = v[:validator_class]
+          validator_class.is_a?(Class) &&
+            defined?(Grape::Validations::Validators::ContractScopeValidator) &&
+            validator_class <= Grape::Validations::Validators::ContractScopeValidator
+        end
+
+        return unless contract_validation
+
+        # The contract instance is stored in opts[:schema]
+        contract_validation.dig(:opts, :schema)
+      end
+
       def build_contract_schema
-        settings = route.respond_to?(:settings) ? route.settings : {}
-        contract = route.options[:contract] || settings[:contract]
+        contract = find_contract
         return unless contract
 
         schema_obj = if contract.respond_to?(:schema)
@@ -299,6 +359,62 @@ module GrapeOAS
       rescue NoMethodError
         nil
       end
+
+      def convert_contract_schema_to_params(schema)
+        return [] unless schema.respond_to?(:properties)
+
+        params = []
+        param_docs = contract_param_documentation
+        path_params = path_param_names
+
+        schema.properties.each do |name, prop_schema|
+          name_s = name.to_s
+          next if path_params.include?(name_s)
+
+          required = schema.required&.any? { |r| r.to_s == name_s } || false
+          doc = param_docs[name_s] || {}
+          params << build_query_parameter(name_s, prop_schema, required, doc)
+        end
+
+        params
+      end
+
+      def should_convert_contract_to_query_params?
+        http_method = operation.http_method.to_s.downcase
+        return false unless Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method)
+
+        !(route.options.dig(:documentation, :request_body) || route.options[:request_body])
+      end
+
+      def build_query_parameter(name, schema, required, doc = {})
+        style = doc.fetch(:style) { doc["style"] }
+        explode = doc.fetch(:explode) { doc["explode"] }
+        description = doc[:desc] || doc[:description] || schema.description
+        ApiModel::Parameter.new(
+          location: "query",
+          name: name,
+          required: required,
+          schema: schema,
+          description: description,
+          style: style,
+          explode: explode,
+        )
+      end
+
+      def contract_param_documentation
+        params = documentation_options[:params]
+        return {} unless params.is_a?(Hash)
+
+        params.each_with_object({}) do |(key, value), acc|
+          acc[key.to_s] = value.is_a?(Hash) ? value : {}
+        end
+      end
+
+      def path_param_names
+        names = route.path.scan(RequestParams::ROUTE_PARAM_REGEX)
+        mapped_names = path_param_name_map ? path_param_name_map.values : []
+        (names + mapped_names).map(&:to_s).uniq
+      end
     end
   end
 end

data/lib/grape_oas/api_model_builders/request_params.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "request_params_support/param_location_resolver"
-require_relative "request_params_support/param_schema_builder"
-require_relative "request_params_support/schema_enhancer"
-require_relative "request_params_support/nested_params_builder"
-
 module GrapeOAS
   module ApiModelBuilders
     class RequestParams
@@ -137,6 +132,10 @@ module GrapeOAS
       end
 
       def build_parameter(name, location, required, schema, spec)
+        doc = spec[:documentation] || {}
+        style = doc.fetch(:style) { doc["style"] }
+        explode = doc.fetch(:explode) { doc["explode"] }
+
         ApiModel::Parameter.new(
           location: location,
           name: name,
@@ -144,6 +143,8 @@ module GrapeOAS
           schema: schema,
           description: spec[:documentation]&.dig(:desc) || spec[:desc],
           collection_format: extract_collection_format(spec),
+          style: style,
+          explode: explode,
         )
       end
 

data/lib/grape_oas/api_model_builders/request_params_support/param_schema_builder.rb

@@ -55,7 +55,11 @@ module GrapeOAS
         def build_entity_array_schema(spec, raw_type, doc_type)
           entity_type = resolve_entity_class(extract_entity_type_from_array(spec, raw_type, doc_type))
           items = entity_type ? GrapeOAS.introspectors.build_schema(entity_type, stack: [], registry: {}) : nil
-          items ||= ApiModel::Schema.new(type: sanitize_type(extract_entity_type_from_array(spec, raw_type)))
+          fallback_type = extract_entity_type_from_array(spec, raw_type)
+          items ||= ApiModel::Schema.new(
+            type: sanitize_type(fallback_type),
+            format: Constants.format_for_type(fallback_type),
+          )
           ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items)
         end
 
@@ -76,7 +80,10 @@ module GrapeOAS
           items_schema = if entity
                            GrapeOAS.introspectors.build_schema(entity, stack: [], registry: {})
                          else
-                           ApiModel::Schema.new(type: sanitize_type(items_type))
+                           ApiModel::Schema.new(
+                             type: sanitize_type(items_type),
+                             format: Constants.format_for_type(items_type),
+                           )
                          end
           ApiModel::Schema.new(type: Constants::SchemaTypes::ARRAY, items: items_schema)
         end
@@ -88,18 +95,59 @@ module GrapeOAS
           )
         end
 
-        # Builds oneOf schema for Grape's multi-type notation like "[String, Integer]"
+        # Builds schema for Grape's multi-type notation like "[String, Integer]"
+        # Special case: "[Type, NilClass]" becomes a nullable Type (not oneOf)
         def build_multi_type_schema(type)
           type_names = extract_multi_types(type)
-          schemas = type_names.map do |type_name|
-            ApiModel::Schema.new(type: resolve_schema_type(type_name))
+
+          # OPTIMIZE: [Type, Nil] becomes nullable Type instead of oneOf
+          if nullable_type_pair?(type_names)
+            non_nil_type = type_names.find { |t| !nil_type_name?(t) }
+            return ApiModel::Schema.new(
+              type: resolve_schema_type(non_nil_type),
+              format: Constants.format_for_type(non_nil_type),
+              nullable: true,
+            )
+          end
+
+          # General case: build oneOf schema
+          # Filter out nil types - OpenAPI 3.0 uses nullable property instead
+          has_nil_type = type_names.any? { |t| nil_type_name?(t) }
+          non_nil_types = type_names.reject { |t| nil_type_name?(t) }
+
+          schemas = non_nil_types.map do |type_name|
+            ApiModel::Schema.new(
+              type: resolve_schema_type(type_name),
+              format: Constants.format_for_type(type_name),
+            )
           end
-          ApiModel::Schema.new(one_of: schemas)
+          ApiModel::Schema.new(one_of: schemas, nullable: has_nil_type ? true : nil)
+        end
+
+        # Checks if type_names is a pair of [SomeType, NilType]
+        def nullable_type_pair?(type_names)
+          return false unless type_names.size == 2
+
+          type_names.one? { |t| nil_type_name?(t) }
+        end
+
+        # Checks if the type name represents a nil/null type
+        def nil_type_name?(type_name)
+          normalized = type_name.to_s
+          # Match common nil type patterns:
+          # - "NilClass" (Ruby's nil type)
+          # - "Nil" (shorthand)
+          # - "Foo::Nil", "Types::Nil" (namespaced nil types)
+          normalized == "NilClass" ||
+            normalized == "Nil" ||
+            normalized.end_with?("::Nil")
         end
 
         def build_primitive_schema(raw_type, doc)
+          schema_type = sanitize_type(raw_type)
           ApiModel::Schema.new(
-            type: sanitize_type(raw_type),
+            type: schema_type,
+            format: Constants.format_for_type(raw_type),
             description: doc[:desc],
           )
         end
@@ -138,7 +186,10 @@ module GrapeOAS
           items_type = resolve_schema_type(member_type)
           ApiModel::Schema.new(
             type: Constants::SchemaTypes::ARRAY,
-            items: ApiModel::Schema.new(type: items_type),
+            items: ApiModel::Schema.new(
+              type: items_type,
+              format: Constants.format_for_type(member_type),
+            ),
           )
         end