grape-oas 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e76945cff9198556752b881ff62da8c288a18e3f6447a36b7668d516ed575f4f
-  data.tar.gz: 8f36610d66d2d5935004972fdc063e74316b2a576be030ce7d8a0a903fa43f79
+  metadata.gz: eb455b84bab348e43f6f512e31a9c306ec7deb76ddb5e6267231a3c7495615e7
+  data.tar.gz: 7096893822180fa7da1976ebbc7b20eaea31108aa8829595d2f4b4764e7350da
 SHA512:
-  metadata.gz: df261c7d71e8c228c096484cda70c821e4cdd58f1aad04b31bf402513dd414eff69512a38d9c6ef131de418fd19403c0ddadfc4ae7fe0bd8e12078ffc66e285a
-  data.tar.gz: 233f3e233f053f12f7b9fb2eb4635c8969233b4d8848b61048bf273512cffed54ce9499f473b90b56875c0d429f4d12a46f74148689fa122002a7e049fc1f383
+  metadata.gz: 3cd2cb8c1c03fc8c14c427eb247de87d2a7cc782be02e41bc435e1f400a6eb0d1972dd1ea51e6c8e11f6854b4c4d646692fb80191db9d68b65e4e271604c3772
+  data.tar.gz: ba055b0ad8596358370103f503f009c80a6dd8395983077b6a1573aab4798c9bd5b5fa1d872c6210a57892151ef70d2a19538d3629823f076322e56274e8be4e

data/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.1] - 2026-09-16
+
+### Fixed
+
+- [#110](https://github.com/numbata/grape-oas/pull/110): Honor Grape `desc` `default` / `default_response` as OAS `responses.default` - [@numbata](https://github.com/numbata).
+- [#136](https://github.com/numbata/grape-oas/pull/136): Preserve top-level Grape `desc:` metadata on request-body properties - [@numbata](https://github.com/numbata).
+- [#140](https://github.com/numbata/grape-oas/pull/140): Preserve nullable entity scalars documented with `types:` - [@numbata](https://github.com/numbata).
+- [#142](https://github.com/numbata/grape-oas/pull/142): Normalize symbolic response status keys to numeric HTTP codes - [@numbata](https://github.com/numbata).
+- [#145](https://github.com/numbata/grape-oas/pull/145): Preserve explicitly body-located GET, HEAD, and DELETE parameters - [@numbata](https://github.com/numbata).
+- [#146](https://github.com/numbata/grape-oas/pull/146): Preserve declared path metadata inside nested body parameter groups and always mark path parameters as required, per OAS, even when their Grape declaration is optional - [@numbata](https://github.com/numbata).
+- [#149](https://github.com/numbata/grape-oas/pull/149): Preserve explicitly query/header/path-located nested parameters on POST, PUT, and PATCH routes; reject unrecognized `param_type:`/`in:` values and `path` locations without a matching route capture instead of emitting invalid output; drop OAS 2.0-invalid `cookie` parameters with a warning instead of emitting them - [@numbata](https://github.com/numbata).
+- [#152](https://github.com/numbata/grape-oas/pull/152): Emit only spec-valid OAS 2.0 non-body parameters and warn when unsupported schemas are dropped - [@numbata](https://github.com/numbata).
+
+### Changed
+
+- [#145](https://github.com/numbata/grape-oas/pull/145): Apply route-level body opt-in consistently to flat parameters and `body_name` contracts - [@numbata](https://github.com/numbata).
+
+- [#108](https://github.com/numbata/grape-oas/pull/108): Bump actions/checkout from 6 to 7 - [@dependabot[bot]](https://github.com/dependabot[bot]).
+- [#137](https://github.com/numbata/grape-oas/pull/137): Test against Grape 4.0 in CI - [@numbata](https://github.com/numbata).
+
 ## [1.5.0] - 2026-09-07
 
 ### Added

data/lib/grape_oas/api_model_builders/request.rb

@@ -17,9 +17,11 @@ module GrapeOAS
       end
 
       def build
-        body_schema, route_params = GrapeOAS::ApiModelBuilders::RequestParams
-                                    .new(api: api, route: route, path_param_name_map: path_param_name_map)
-                                    .build
+        body_schema, route_params = RequestParams.new(
+          api: api,
+          route: route,
+          path_param_name_map: path_param_name_map,
+        ).build
 
         contract_schema = build_contract_schema
 
@@ -39,15 +41,6 @@ module GrapeOAS
       private
 
       def append_request_body(body_schema)
-        # OAS spec says GET/HEAD/DELETE "MAY ignore" request bodies
-        # Skip by default unless explicitly allowed via documentation option
-        http_method = operation.http_method.to_s.downcase
-        if Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method)
-          allow_body = route.options.dig(:documentation, :request_body) ||
-                       route.options[:request_body]
-          return unless allow_body
-        end
-
         media_ext = media_type_extensions(Constants::MimeTypes::JSON)
 
         # Set canonical_name if not already set (e.g., DryIntrospector may have set it for polymorphism)
@@ -235,7 +228,9 @@ module GrapeOAS
         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])
+        # Parameter-level body annotations apply to Grape params only; contracts
+        # retain route-level body opt-in semantics.
+        !RequestParamsSupport::ParamLocationResolver.route_body_opted_in?(route)
       end
 
       def build_query_parameter(name, schema, required, doc = {})

data/lib/grape_oas/api_model_builders/request_params.rb

@@ -27,22 +27,36 @@ module GrapeOAS
         has_nested = all_params.keys.any? { |k| k.include?("[") }
 
         if has_nested
-          build_with_nested_params(all_params, route_params)
+          body_schema, parameters = build_with_nested_params(all_params, route_params)
         else
-          build_flat_params(all_params, route_params)
+          body_schema, parameters = build_flat_params(all_params, route_params)
         end
+
+        [body_schema, parameters]
       end
 
       private
 
       # Builds params when nested structures are detected.
       def build_with_nested_params(all_params, route_params)
-        body_schema = nested_params_builder.build(all_params, path_params: route_params)
+        body_params = nested_body_params(all_params, route_params)
+        body_schema = nested_params_builder.build(body_params, path_params: route_params)
         non_body_params = extract_non_body_params(all_params, route_params)
 
         [body_schema, non_body_params]
       end
 
+      def nested_body_params(all_params, route_params)
+        body_roots = all_params.filter_map do |name, spec|
+          next if name.include?("[")
+
+          location = location_resolver.resolve(name: name, spec: spec, route_params: route_params, route: route)
+          name if location == "body"
+        end.to_set
+
+        all_params.select { |name, _spec| body_roots.include?(name.split("[", 2).first) }
+      end
+
       # Builds params for flat (non-nested) structures.
       def build_flat_params(all_params, route_params)
         body_schema = ApiModel::Schema.new(type: Constants::SchemaTypes::OBJECT)
@@ -72,33 +86,38 @@ module GrapeOAS
       end
 
       # Extracts non-body params (path, query, header) from flat params.
-      # For non-body HTTP methods (GET, HEAD, DELETE), also includes nested params
-      # as flat query parameters with bracket notation (e.g., "tax_id[type]"),
-      # unless request_body is explicitly enabled.
+      # Nested params (bracket notation, e.g. "tax_id[type]") are included as
+      # flat non-body parameters, taking their parent's resolved location,
+      # regardless of HTTP method — a nested Hash explicitly documented
+      # `in: "header"` on a write route (POST/PUT/PATCH) still belongs in
+      # the header, not the body.
       def extract_non_body_params(all_params, route_params)
         params = []
-        http_method = route.request_method.to_s.downcase
-        flatten_nested = should_flatten_nested_to_query?(http_method, all_params)
 
         all_params.each do |name, spec|
           # Skip hidden params
           next if location_resolver.hidden_parameter?(spec)
 
-          is_nested = name.include?("[")
-          is_hash_param = location_resolver.body_param?(spec)
+          if name.include?("[")
+            root = name.split("[", 2).first
+            root_spec = all_params[root] || {}
+            next if location_resolver.hidden_parameter?(root_spec)
 
-          # For nested bracket params (e.g., "tax_id[type]"), include as query params
-          # for non-body HTTP methods (unless request_body is explicitly enabled)
-          if is_nested
-            next unless flatten_nested
+            root_location = location_resolver.resolve(name: root, spec: root_spec, route_params: route_params, route: route)
+            next if root_location == "body"
+            # A Hash root can itself be a real route capture (e.g. ":filter"),
+            # but that doesn't make its bracket children path segments too —
+            # only the root itself matches the URL template.
+            next if root_location == "path"
 
-            params << build_parameter(name, "query", spec[:required] || false, schema_builder.build(spec), spec)
+            params << build_parameter(name, root_location, spec[:required] || false, schema_builder.build(spec), spec)
             next
           end
 
-          # Skip Hash type params (they're handled via nested bracket params above
-          # or via body schema for POST/PUT/PATCH)
-          next if is_hash_param
+          # Skip Hash type params with nested children of their own (they're
+          # handled via the nested bracket branch above or via body schema).
+          # A childless Hash falls through to the generic path below.
+          next if location_resolver.hash_param?(spec) && all_params.keys.any? { |k| k.start_with?("#{name}[") }
 
           location = location_resolver.resolve(
             name: name,
@@ -115,28 +134,6 @@ module GrapeOAS
         params
       end
 
-      # Determines whether nested params should be flattened to query params.
-      # Returns true for GET/HEAD/DELETE unless body is explicitly requested via:
-      # - route-level `request_body: true` option
-      # - any parameter with `documentation: { in: 'body' }` or `documentation: { param_type: 'body' }`
-      def should_flatten_nested_to_query?(http_method, all_params)
-        return false unless Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method)
-
-        # If request_body is explicitly enabled at route level, use body schema
-        return false if route.options.dig(:documentation, :request_body) || route.options[:request_body]
-
-        # If any parameter is explicitly marked as body, use body schema
-        has_explicit_body_param = all_params.any? do |name, spec|
-          next false if name.include?("[") # Skip bracket params, check parent Hash params only
-
-          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
-          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
-          param_type == "body" || in_location == "body"
-        end
-
-        !has_explicit_body_param
-      end
-
       def build_parameter(name, location, required, schema, spec)
         doc = spec[:documentation] || {}
         style = doc.fetch(:style) { doc["style"] }
@@ -145,7 +142,7 @@ module GrapeOAS
         ApiModel::Parameter.new(
           location: location,
           name: name,
-          required: required,
+          required: location == "path" || required,
           schema: schema,
           description: spec[:documentation]&.dig(:desc) || spec[:desc],
           collection_format: extract_collection_format(spec),

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

@@ -30,7 +30,6 @@ module GrapeOAS
 
           top_level.each do |name, spec|
             next if path_params.include?(name)
-            next if ParamLocationResolver.explicit_non_body_param?(spec)
             next if ParamLocationResolver.hidden_parameter?(spec)
 
             child_schema = @schema_builder.build(spec)

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

@@ -5,6 +5,12 @@ module GrapeOAS
     module RequestParamsSupport
       # Resolves the location (path, query, body, header) for a parameter.
       class ParamLocationResolver
+        # Locations `param_type:`/`in:` may explicitly name. An unrecognized
+        # value (a typo, or a grape-swagger location this library doesn't
+        # resolve to, like `formData`) is treated as unset rather than
+        # emitted verbatim, since nothing downstream validates `Parameter#location`.
+        VALID_EXPLICIT_LOCATIONS = %w[body query header path cookie].freeze
+
         # Determines the location for a parameter.
         #
         # @param name [String] the parameter name
@@ -18,29 +24,14 @@ module GrapeOAS
           extract_from_spec(spec, route)
         end
 
-        # Checks if a parameter should be in the request body.
-        # Supports both `param_type: 'body'` and `in: 'body'` for grape-swagger compatibility.
-        #
-        # @param spec [Hash] the parameter specification
-        # @return [Boolean] true if it's a body parameter
-        def self.body_param?(spec)
-          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
-          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
-
-          param_type == "body" || in_location == "body" || [Hash, "Hash"].include?(spec[:type])
-        end
-
-        # Checks if a parameter is explicitly marked as NOT a body param.
-        # Supports both `param_type` and `in` for grape-swagger compatibility.
+        # Checks if a parameter is a Hash type. Hash parents are represented
+        # by their children (nested params) or the request body, never
+        # themselves as a parameter.
         #
         # @param spec [Hash] the parameter specification
-        # @return [Boolean] true if explicitly non-body
-        def self.explicit_non_body_param?(spec)
-          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
-          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
-          location = param_type || in_location
-
-          location && %w[query header path].include?(location)
+        # @return [Boolean] true if the parameter type is Hash
+        def self.hash_param?(spec)
+          [Hash, "Hash"].include?(spec[:type])
         end
 
         # Checks if a parameter should be hidden from documentation.
@@ -56,6 +47,10 @@ module GrapeOAS
           hidden
         end
 
+        def self.route_body_opted_in?(route)
+          !!(route.options[:body_name] || route.options.dig(:documentation, :request_body) || route.options[:request_body])
+        end
+
         class << self
           private
 
@@ -70,24 +65,35 @@ module GrapeOAS
           # Note: If both `param_type` and `in` are specified, `param_type` takes precedence.
           # For example, `{ param_type: 'query', in: 'body' }` will be treated as query.
           #
+          # `resolve` already returns "path" for an actual route capture before
+          # calling this method, so an explicit `in: "path"` / `param_type: "path"`
+          # reaching here is always a mismatch (the name can never appear in the
+          # URL template) and is ignored, same as an unrecognized location.
+          #
           # @param spec [Hash] the parameter specification
           # @param route [Object] the Grape route object
           # @return [String] the parameter location
           def extract_from_spec(spec, route)
-            # If body_name is set on the route, treat non-path params as body by default
-            param_type = spec.dig(:documentation, :param_type)
-            in_location = spec.dig(:documentation, :in)
-            return "body" if route.options[:body_name] && !param_type && !in_location
+            location = explicit_location(spec)
+            location = nil if location == "path"
+            return "body" if route_body_opted_in?(route) && location.nil?
 
             # Support both param_type and in for grape-swagger compatibility
             # param_type takes precedence over in when both are specified
-            explicit_location = (param_type || in_location)&.to_s&.downcase
-            return explicit_location if explicit_location
+            return location if location
 
             # Default: body for write methods (POST/PUT/PATCH), query for read methods (GET/DELETE/HEAD)
             http_method = route.request_method.to_s.downcase
             Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method) ? "query" : "body"
           end
+
+          def explicit_location(spec)
+            doc = spec[:documentation] || {}
+            param_type = doc[:param_type] || doc["param_type"]
+            in_location = doc[:in] || doc["in"]
+            location = (param_type || in_location)&.to_s&.downcase
+            location if VALID_EXPLICIT_LOCATIONS.include?(location)
+          end
         end
       end
     end

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

@@ -119,19 +119,17 @@ module GrapeOAS
           type_names = extract_multi_types(type)
 
           # 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) }
+          if (nullable_type = Constants.nullable_type(type_names))
             return ApiModel::Schema.new(
-              type: resolve_schema_type(non_nil_type),
-              format: Constants.format_for_type(non_nil_type),
+              type: resolve_schema_type(nullable_type),
+              format: Constants.format_for_type(nullable_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) }
+          nil_types, non_nil_types = type_names.partition { |type_name| Constants.nil_type?(type_name) }
 
           schemas = non_nil_types.map do |type_name|
             ApiModel::Schema.new(
@@ -139,26 +137,9 @@ module GrapeOAS
               format: Constants.format_for_type(type_name),
             )
           end
-          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")
+          schema = ApiModel::Schema.new(one_of: schemas)
+          schema.nullable = true if nil_types.any?
+          schema
         end
 
         def build_primitive_schema(raw_type, doc)

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

@@ -13,7 +13,7 @@ module GrapeOAS
         def self.apply(schema, spec, doc)
           nullable = extract_nullable(doc)
 
-          schema.description ||= doc[:desc]
+          schema.description ||= doc[:desc] || spec[:desc]
           # Preserve existing nullable: true (e.g., from [Type, Nil] optimization)
           schema.nullable = (schema.nullable || nullable) if schema.respond_to?(:nullable=)
 

data/lib/grape_oas/api_model_builders/response.rb

@@ -48,7 +48,11 @@ module GrapeOAS
       # Parsers are tried in order of priority
       def response_specs
         parser = parsers.find { |p| p.applicable?(route) }
-        parser ? parser.parse(route) : []
+        return [] unless parser
+
+        parser.parse(route).each do |spec|
+          spec[:code] = ResponseParsers::Base.normalize_status_code(spec[:code])
+        end
       end
 
       def parsers

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

@@ -29,6 +29,17 @@ module GrapeOAS
 
         private
 
+        def normalize_status_code(status)
+          return status unless status.is_a?(Symbol)
+
+          status_name = status.to_s
+          return status_name if status_name == "default" || status_name.match?(/\A[1-5](?:\d{2}|XX)\z/)
+
+          Rack::Utils.status_code(status)
+        end
+
+        module_function :normalize_status_code
+
         # Extract status code from hash, supporting multiple key names
         def extract_status_code(hash, default_code)
           hash[:code] || hash[:status] || hash[:http_status] || default_code

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

@@ -17,10 +17,10 @@ module GrapeOAS
           doc_resps = route.options.dig(:documentation, :responses)
           return [] unless doc_resps.is_a?(Hash)
 
-          doc_resps.map do |code, doc|
+          specs = doc_resps.map do |code, doc|
             doc = normalize_hash_keys(doc)
             {
-              code: code,
+              code: normalize_status_code(code),
               message: extract_description(doc),
               headers: doc[:headers],
               entity: extract_entity(doc, route.options[:entity]),
@@ -28,6 +28,9 @@ module GrapeOAS
               examples: doc[:examples]
             }
           end
+          return specs if specs.any? { |spec| spec[:code].to_s == HttpCodesParser::DEFAULT_RESPONSE_CODE }
+
+          specs + HttpCodesParser.new.default_response_specs(route)
         end
       end
     end

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,9 +57,59 @@ module GrapeOAS
         def parse_values(data, route)
           return [] unless data.is_a?(Hash)
 
-          %i[http_codes failure success].flat_map do |key|
+          specs = %i[http_codes failure success].flat_map do |key|
             parse_value(data[key], route)
           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 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)
@@ -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)
@@ -122,17 +185,19 @@ module GrapeOAS
         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
+          spec = 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
+          spec[:code] = normalize_status_code(spec[:code])
+          spec
         end
 
         def normalize_hash_entry(entry, route)

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/oas2/parameter.rb

@@ -28,7 +28,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 +41,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 +100,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 +109,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
@@ -111,10 +154,10 @@ module GrapeOAS
           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/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
@@ -206,8 +214,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.5.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-oas
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Andrei Subbota
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape