grape-oas 1.4.0 → 1.5.1

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

@@ -12,6 +12,7 @@ module GrapeOAS
       OBJECT = "object"
       ARRAY = "array"
       FILE = "file"
+      NULL = "null"
 
       ALL = [STRING, INTEGER, NUMBER, BOOLEAN, OBJECT, ARRAY, FILE].freeze
     end
@@ -45,6 +46,11 @@ module GrapeOAS
       TYPE_ARRAY = :type_array
       # OAS 2.0: emits `"x-nullable": true` extension
       EXTENSION = :extension
+
+      # Version-specific defaults used by exporters
+      OAS2_DEFAULT = EXTENSION
+      OAS3_DEFAULT = KEYWORD
+      OAS31_DEFAULT = TYPE_ARRAY
     end
 
     # Maximum number of elements to expand from a non-numeric Range into an enum array.
@@ -52,12 +58,32 @@ module GrapeOAS
     MAX_ENUM_RANGE_SIZE = 100
 
     # Regex patterns for Grape's stringified type notations.
-    # Grape converts `type: [SomeClass]` to "[SomeClass]" and
-    # `type: [String, Integer]` to "[String, Integer]" for documentation.
+    # Grape's ParamsDocumentation TypeCache stores `coerce_type.to_s`:
+    # - `type: [SomeClass]` / `type: Array[SomeClass]` → "[SomeClass]" (Array#to_s)
+    # - `types: [String, Integer]` → "[String, Integer]" (Array#to_s of the types list)
+    # - Grape 3.3+ `type: Array[Integer, String]` → "Array[Integer, String]"
+    #   (VariantCollectionCoercer#to_s, grape#2758). Distinct from the `types:`
+    #   form so a collection of variant members is not confused with a scalar
+    #   that accepts multiple types. `Set[...]` is the same for Set containers.
     module TypePatterns
       CONST_NAME = /(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*/
-      TYPED_ARRAY = /\A\[(?<inner>#{CONST_NAME})\]\z/
+      TYPED_ARRAY = /\A(?:(?<container>Array|Set))?\[(?<inner>#{CONST_NAME})\]\z/
       MULTI_TYPE = /\A\[(#{CONST_NAME}(?:,\s*#{CONST_NAME})+)\]\z/
+      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
@@ -95,7 +121,7 @@ module GrapeOAS
       "float" => { type: SchemaTypes::NUMBER, format: "float" },
       "bigdecimal" => { type: SchemaTypes::NUMBER, format: "double" },
       "string" => { type: SchemaTypes::STRING },
-      "integer" => { type: SchemaTypes::INTEGER, format: "int32" },
+      "integer" => { type: SchemaTypes::INTEGER },
       "number" => { type: SchemaTypes::NUMBER, format: "double" },
       "boolean" => { type: SchemaTypes::BOOLEAN },
       "grape::api::boolean" => { type: SchemaTypes::BOOLEAN },

data/lib/grape_oas/documentation_extension.rb

@@ -3,9 +3,7 @@
 module GrapeOAS
   module DocumentationExtension
     # Primary entry for grape-oas documentation
-    def add_oas_documentation(**options)
-      return if options.delete(:hide_documentation_path)
-
+    def add_oas_documentation(hide_documentation_path: true, **options)
       # Prefer grape-oas namespaced options to avoid clashing with grape-swagger
       default_mount_path = options.delete(:oas_mount_path) ||
                            options.delete(:mount_path) ||
@@ -25,13 +23,13 @@ module GrapeOAS
       api = self
 
       mount_paths.each do |key, path|
-        add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api)
+        add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api, hidden: hide_documentation_path)
       end
     end
 
-    def add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api)
+    def add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api, hidden: false)
       # Main route without namespace filter
-      add_route(path) do
+      add_route(path, hidden: hidden) do
         GrapeOAS::DocumentationExtension.generate_documentation(
           self, api, key, default_format, cache_control, etag_value, options, nil,
         )
@@ -39,7 +37,7 @@ module GrapeOAS
 
       # Route with namespace filter: /swagger_doc/:namespace
       # Supports nested namespaces via *namespace (catches slashes)
-      add_route("#{path}/*namespace") do
+      add_route("#{path}/*namespace", hidden: hidden) do
         namespace_filter = params[:namespace]&.sub(/\.json$/, "")
         GrapeOAS::DocumentationExtension.generate_documentation(
           self, api, key, default_format, cache_control, etag_value, options, namespace_filter,
@@ -89,10 +87,10 @@ module GrapeOAS
     private
 
     # Minimal route mounting helper
-    def add_route(path, &block)
+    def add_route(path, hidden: false, &block)
       api_class = self
       namespace do
-        get(path) { instance_exec(api_class, &block) }
+        get(path, hidden: hidden) { instance_exec(api_class, &block) }
       end
     end
 

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

@@ -47,10 +47,21 @@ module GrapeOAS
           end
         end
 
-        def index_schema(schema, index)
-          return unless schema.respond_to?(:canonical_name) && schema.canonical_name
+        def index_schema(schema, index, seen = Set.new)
+          return unless schema
+
+          schema_id = schema.object_id
+          return if seen.include?(schema_id)
 
-          index[schema.canonical_name] ||= schema
+          seen << schema_id
+          index[schema.canonical_name] ||= schema if schema.respond_to?(:canonical_name) && schema.canonical_name
+          index_schema(schema.items, index, seen) if schema.respond_to?(:items) && schema.items
+          schema.properties.each_value { |child| index_schema(child, index, seen) } if schema.respond_to?(:properties) && schema.properties
+          %i[all_of one_of any_of].each do |composition|
+            next unless schema.respond_to?(composition)
+
+            Array(schema.public_send(composition)).each { |child| index_schema(child, index, seen) }
+          end
         end
 
         def collect_refs(schema, pending, seen = Set.new)

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

@@ -15,8 +15,10 @@ module GrapeOAS
           {
             "consumes" => consumes,
             "produces" => produces,
-            "parameters" => Parameter.new(@op, @ref_tracker, nullable_strategy: strategy).build,
-            "responses" => Response.new(@op.responses, @ref_tracker, nullable_strategy: strategy).build
+            "parameters" => Parameter.new(@op, @ref_tracker, nullable_strategy: strategy,
+                                                             composition_extensions: @options[:composition_extensions],).build,
+            "responses" => Response.new(@op.responses, @ref_tracker, nullable_strategy: strategy,
+                                                                     composition_extensions: @options[:composition_extensions],).build
           }
         end
 

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

@@ -5,7 +5,7 @@ module GrapeOAS
     module OAS2
       class Parameter
         PRIMITIVE_MAPPINGS = {
-          Constants::SchemaTypes::INTEGER => { type: Constants::SchemaTypes::INTEGER, format: "int32" },
+          Constants::SchemaTypes::INTEGER => { type: Constants::SchemaTypes::INTEGER },
           "long" => { type: Constants::SchemaTypes::INTEGER, format: "int64" },
           "float" => { type: Constants::SchemaTypes::NUMBER, format: "float" },
           "double" => { type: Constants::SchemaTypes::NUMBER, format: "double" },
@@ -18,24 +18,76 @@ module GrapeOAS
           "uuid" => { type: Constants::SchemaTypes::STRING, format: "uuid" }
         }.freeze
 
-        def initialize(operation, ref_tracker = nil, nullable_strategy: nil)
+        def initialize(operation, ref_tracker = nil, nullable_strategy: nil, composition_extensions: false)
           @op = operation
           @ref_tracker = ref_tracker
           @nullable_strategy = nullable_strategy
+          @composition_extensions = composition_extensions
         end
 
+        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 << build_body_parameter(@op.request_body) if @op.request_body
+          params = representable_parameters.map { |param| build_parameter(param) }
+          if @op.request_body
+            if form_only_request?
+              params.concat(build_form_parameters(@op.request_body))
+            else
+              params << build_body_parameter(@op.request_body)
+            end
+          end
           params
         end
 
         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"
@@ -48,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
             {
@@ -57,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
@@ -76,6 +128,7 @@ module GrapeOAS
           result["maxLength"] = schema.max_length if schema.respond_to?(:max_length) && !schema.max_length.nil?
           result["minItems"] = schema.min_items if schema.respond_to?(:min_items) && !schema.min_items.nil?
           result["maxItems"] = schema.max_items if schema.respond_to?(:max_items) && !schema.max_items.nil?
+          result["uniqueItems"] = true if schema.respond_to?(:unique_items) && schema.unique_items
           result["pattern"] = schema.pattern if schema.respond_to?(:pattern) && schema.pattern
           result["enum"] = normalize_enum(schema.enum, result["type"]) if schema.respond_to?(:enum) && schema.enum
           result["default"] = schema.default if schema.respond_to?(:default) && !schema.default.nil?
@@ -84,28 +137,77 @@ module GrapeOAS
         def normalize_enum(enum_vals, type)
           return nil unless enum_vals.is_a?(Array)
 
-          coerced = enum_vals.map do |v|
-            case type
-            when Constants::SchemaTypes::INTEGER then v.to_i if v.respond_to?(:to_i)
-            when Constants::SchemaTypes::NUMBER then v.to_f if v.respond_to?(:to_f)
-            else v
-            end
-          end.compact
+          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 = coerced.uniq
+          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(schema.items) if schema.items
           return unless param.collection_format
 
           valid_formats = %w[csv ssv tsv pipes multi brackets]
           result["collectionFormat"] = param.collection_format if valid_formats.include?(param.collection_format)
         end
 
+        def form_only_request?
+          consumes = Array(@op.consumes)
+          consumes.any? && consumes.all? { |mime| FORM_MEDIA_TYPES.include?(mime) }
+        end
+
+        def build_form_parameters(request_body)
+          schema = Array(request_body.media_types).first&.schema
+          return [] unless schema
+
+          unless [nil, "object"].include?(schema.type) && !composition?(schema)
+            raise ArgumentError, "OAS2 form bodies must have object properties; use OAS3 for this request schema"
+          end
+
+          required = Array(schema.required).map(&:to_s)
+          schema.properties.map do |name, property_schema|
+            unless form_property?(property_schema)
+              raise ArgumentError, "OAS2 cannot represent form field #{name.inspect}; use OAS3 for complex form fields"
+            end
+
+            build_parameter(
+              ApiModel::Parameter.new(
+                name: name.to_s,
+                location: "formData",
+                required: required.include?(name.to_s),
+                description: property_schema.description,
+                schema: property_schema,
+              ),
+            )
+          end
+        end
+
+        def form_property?(schema, array_item: false)
+          return false unless schema && !composition?(schema)
+          return false if array_item && schema.canonical_name
+          return form_property?(schema.items, array_item: true) if schema.type == "array"
+
+          types = array_item ? %w[string integer number boolean] : %w[string integer number boolean file]
+          types.include?(schema.type)
+        end
+
+        def composition?(schema)
+          schema.all_of&.any? || schema.one_of&.any? || schema.any_of&.any?
+        end
+
         def build_body_parameter(request_body)
           schema = build_body_schema(request_body)
           name = derive_body_name(request_body)
@@ -139,10 +241,11 @@ module GrapeOAS
         def build_schema_or_ref(schema)
           if schema.respond_to?(:canonical_name) && schema.canonical_name
             @ref_tracker << schema.canonical_name if @ref_tracker
-            ref_name = schema.canonical_name.gsub("::", "_")
+            ref_name = GrapeOAS.schema_ref_name.call(schema.canonical_name)
             { "$ref" => "#/definitions/#{ref_name}" }
           else
-            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy).build
+            Schema.new(schema, @ref_tracker, nullable_strategy: @nullable_strategy,
+                                             composition_extensions: @composition_extensions,).build
           end
         end
       end

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

@@ -12,6 +12,7 @@ module GrapeOAS
         def build_operation(operation)
           Operation.new(operation, @ref_tracker,
                         nullable_strategy: @options[:nullable_strategy],
+                        composition_extensions: @options[:composition_extensions],
                         suppress_default_error_response: @options[:suppress_default_error_response],).build
         end
       end

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

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