grape-oas 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e76945cff9198556752b881ff62da8c288a18e3f6447a36b7668d516ed575f4f
-  data.tar.gz: 8f36610d66d2d5935004972fdc063e74316b2a576be030ce7d8a0a903fa43f79
+  metadata.gz: 2d771c74ede3e601d65419900f26aa0ad36d785a649e09184a9e6755f4749fe7
+  data.tar.gz: 55bef62d1b83ccbd6f57cc469ec6ff81aea4b00c38fef892542fa5bc2f0588b0
 SHA512:
-  metadata.gz: df261c7d71e8c228c096484cda70c821e4cdd58f1aad04b31bf402513dd414eff69512a38d9c6ef131de418fd19403c0ddadfc4ae7fe0bd8e12078ffc66e285a
-  data.tar.gz: 233f3e233f053f12f7b9fb2eb4635c8969233b4d8848b61048bf273512cffed54ce9499f473b90b56875c0d429f4d12a46f74148689fa122002a7e049fc1f383
+  metadata.gz: 9d3f8cc1eeee662d60fdd0574970ed350416dcc9770df2536b7d7d7f017292bcc4338f47cb203cd2d486189d32d614b56d12c74efa83f4c52eabfb69df171b0d
+  data.tar.gz: 86d67570e32b7aafa0290963801c2b0f673fce6d1dde815b93cc2fd5ee8794c898541987382b7910b217e62b58807fdd5f9a6e940d427f82371a23b9ecbfaf84

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.6.0] - 2026-09-21
+
+### Added
+
+- [#89](https://github.com/numbata/grape-oas/pull/89): Add `GrapeOAS.entity_exposure_required_default` to make entity exposures without explicit required metadata optional in generated schemas - [@abeljim8am](https://github.com/abeljim8am).
+
+### Fixed
+
+- [#158](https://github.com/numbata/grape-oas/pull/158): Emit bare item references for nullable arrays of entities instead of redundant `allOf` wrappers - [@numbata](https://github.com/numbata).
+- [#72](https://github.com/numbata/grape-oas/pull/72): Infer `201` for POST success responses without an explicit status; honor entity `default_status:` for all methods, omitting content for bodyless statuses - [@olivier-thatch](https://github.com/olivier-thatch).
+- [#154](https://github.com/numbata/grape-oas/pull/154): Keep nullable enum members aligned with the emitted null representation across OAS versions - [@numbata](https://github.com/numbata).
+- [#153](https://github.com/numbata/grape-oas/pull/153): Reject colliding schema reference names instead of silently overwriting definitions - [@numbata](https://github.com/numbata).
+- [#106](https://github.com/numbata/grape-oas/pull/106): Apply `nullable` to the array, not its items, on `is_array: true` entity exposures - [@olivier-thatch](https://github.com/olivier-thatch).
+
+### Changed
+
+- [#155](https://github.com/numbata/grape-oas/pull/155): Fail generation when explicit `models:` entries cannot be resolved or introspected instead of silently omitting them - [@numbata](https://github.com/numbata).
+
+## [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/UPGRADING.md

@@ -1,5 +1,43 @@
 # Upgrading grape-oas
 
+### Upgrading to >= 1.6.0
+
+#### Schema reference-name collisions stop generation
+
+Distinct schemas that map to the same OAS reference name now raise
+`ArgumentError` instead of silently overwriting one schema. The error identifies
+both canonical names and the shared reference name.
+
+Rename one of the schemas or configure a mapping that produces unique names for
+your application. For example, dots distinguish Ruby namespaces from underscores
+while remaining valid in OAS reference names:
+
+```ruby
+GrapeOAS.schema_ref_name = ->(name) { name.gsub("::", ".") }
+```
+
+#### Invalid explicit models stop generation
+
+Entries passed through `models:` that cannot be resolved or introspected now
+stop generation instead of silently disappearing from the generated document.
+Exceptions from custom introspectors propagate with their original type and
+backtrace.
+
+Check model names, remove unsupported entries, and fix errors raised by custom
+introspectors before generating the document again.
+
+#### POST success responses use consistent defaults
+
+POST `success:` declarations without an explicit response code or
+`default_status:` now infer status `201`. Entity response paths that previously
+hardcoded `200` now use the same precedence. Undocumented POST responses already
+inferred `201`.
+
+If a POST endpoint returns `200`, set `code: 200` in the response declaration or
+`default_status: 200` on the route. Explicit response codes take precedence over
+`default_status:`. Entity responses now honor `default_status:` for every HTTP
+method; bodyless statuses such as `204` omit response content.
+
 ### Upgrading to >= 1.5.0
 
 When upgrading from 1.4.0, regenerate your OpenAPI documents and review the diff before regenerating clients.

data/lib/grape_oas/api_model_builder.rb

@@ -54,11 +54,12 @@ module GrapeOAS
     def build_registered_schemas(models)
       return [] unless models
 
-      Array(models).filter_map do |model|
+      Array(models).map do |model|
         model = model.constantize if model.is_a?(String)
-        GrapeOAS.introspectors.build_schema(model, stack: [], registry: {})
-      rescue StandardError
-        nil
+        schema = GrapeOAS.introspectors.build_schema(model, stack: [], registry: {})
+        raise ArgumentError, "No introspector can build a schema for #{model.inspect}" unless schema
+
+        schema
       end
     end
   end

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
@@ -50,6 +61,12 @@ module GrapeOAS
 
           hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
         end
+
+        def default_response_code(route, success:)
+          return route.options[:default_status] if route.options[:default_status]
+
+          success && route.request_method.to_s.upcase == "POST" ? 201 : 200
+        end
       end
     end
   end

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

@@ -3,8 +3,9 @@
 module GrapeOAS
   module ApiModelBuilders
     module ResponseParsers
-      # Parser that creates a default 200 response when no responses are defined
-      # This is the fallback parser used when no other parsers are applicable
+      # Parser that creates a default success response when no responses are defined.
+      # Status code defaults to 201 for POST routes and 200 for all other methods.
+      # This is the fallback parser used when no other parsers are applicable.
       class DefaultResponseParser
         include Base
 
@@ -14,12 +15,8 @@ module GrapeOAS
         end
 
         def parse(route)
-          inferred = route.options[:default_status]
-          inferred ||= route.request_method.to_s.upcase == "POST" ? 201 : 200
-          default_code = inferred.to_s
-
           [{
-            code: default_code,
+            code: default_response_code(route, success: true).to_s,
             message: "Success",
             entity: route.options[:entity],
             headers: nil

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