gitlab-grape-openapi 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79aec4f1d4657df18a7ccbcf6b689c9f00f8f0b5c940d508da34b05112aa8432
-  data.tar.gz: 275e4524ae0d61929af41ca0540ff080f49790f0a2cbb1308f4a0e6d6b79f75f
+  metadata.gz: 0abbc799f3af1d884ee9e543865658f3709007fe0cb09febea2792678c09d071
+  data.tar.gz: 815581f530dbedff8b9cd89135507640df91e58435f42a62c78bd1d213388d46
 SHA512:
-  metadata.gz: cd0dfaa149fb09c6a61bd2b8c9256d506e6bc62da716faed13e9b0c2f48932efed53b69315c330d1f91f8bf550bb5728fc284865748966b39f15b4a7d7598c67
-  data.tar.gz: c937af8a3e5f1a4f80ae412e7d444f1b11c7d30268b5c64dd9441c3e2b6125db1b325387effa1ec917821211ee12ca7e140dd1f9e659bcab039c86d99c3e3db4
+  metadata.gz: 2574c73242cbbb597331b2919a05ced49beba5dbe733683d88cf90d1ae71d2e55ecffbc2443b399ad5d52e9dc74e53cee7360f3e998b1bc0e8cf7ae8c4603138
+  data.tar.gz: 2bcf5665113a86d6aee987a543fb101ce582bda2801498765a89ca5c42432b8da9d6461bafeb4cfea11f522cbf75ea77497b8ce580329c088ab0ca485007b795

data/README.md

@@ -185,6 +185,7 @@ Generator
 │   ├── ParameterConverter  - Converts endpoint parameters
 │   ├── ResponseConverter   - Converts endpoint responses
 │   └── RequestBodyConverter - Converts request bodies
+├── MediaTypeResolver   - Maps declared media types to response schemas
 └── TypeResolver        - Maps Ruby/Grape types to OpenAPI types
 ```
 
@@ -194,6 +195,54 @@ Generator
 - **RequestBodyRegistry** - Tracks request body schemas
 - **TagRegistry** - Tracks API tags
 
+### Response media types
+
+Responses default to `application/json`, described by the `$ref` of the entity
+declared with `success` / `entity`. Endpoints that return a file or plain text
+instead declare their media type with `produces` in the `desc` block:
+
+```ruby
+desc 'Download an export' do
+  produces %w[application/octet-stream]
+  success code: 200
+end
+get ':id/export/download' do
+  # ...
+end
+```
+
+which becomes:
+
+```yaml
+'200':
+  description: OK
+  content:
+    application/octet-stream:
+      schema:
+        type: string
+        format: binary
+```
+
+`produces` accepts a bare String as well as an Array, and each declared type
+gets its own entry in `content`. The mapping is:
+
+| Declared media type | Emitted schema |
+| ------------------- | -------------- |
+| `application/octet-stream`, `application/gzip`, `application/x-tar` | `{ type: string, format: binary }` |
+| `text/*`, `application/yaml` | `{ type: string }` |
+| `application/json` | none — the entity `$ref` describes it |
+
+A type outside this table is **skipped** rather than guessed at, since assuming
+"binary" would misdescribe a structured payload such as `application/xml`. The
+response keeps its bare shape, so a new media type needs adding to
+`MediaTypeResolver` before it appears in the spec.
+
+`produces` only affects the success response; failure responses stay JSON.
+
+A route that declares `success File` (with no `produces`) is treated as
+`application/octet-stream`, matching `grape-swagger`. An explicit `produces`
+takes precedence, so it can override that inference.
+
 ### Optional path segments
 
 Grape lets a route mark a path segment as optional with parentheses, e.g.

data/lib/gitlab/grape_openapi/concerns/constraint_applier.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Applies the `values:` and `default:` parameter constraints to an already-built schema.
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      module ConstraintApplier
+        include Serializable
+
+        private
+
+        # values: on an array-typed parameter constrains each element, so it belongs
+        # on items.enum rather than on the array schema itself.
+        def apply_array_enum!(schema, values)
+          return unless schema[:type] == 'array' && schema[:items].is_a?(Hash)
+          return unless values.is_a?(Array)
+
+          schema[:items][:enum] = values
+        end
+
+        def apply_default!(schema, default, example: nil)
+          return if default.nil?
+
+          members = schema[:oneOf] || schema[:anyOf]
+          return apply_union_default!(members, default) if members
+
+          value = resolve_default(default, example: example)
+          schema[:default] = value unless value.nil?
+        end
+
+        # `example` is unused here; ParameterConverter overrides this to feed it to its time serializer.
+        def resolve_default(default, example: nil) # rubocop:disable Lint/UnusedMethodArgument -- overridden
+          return unless serializable?(default)
+
+          default
+        end
+
+        # When a union (oneOf) schema has a `default:`, attach it to every member
+        # whose schema can accept the default value. For arrays this includes
+        # checking the items type so `[1, 2]` lands on `items: { type: integer }`
+        # but not on `items: { type: string }`. Empty arrays are type-agnostic
+        # and attach to all array members.
+        def apply_union_default!(members, default)
+          return unless serializable?(default)
+
+          members.each do |member|
+            member[:default] = default if member_accepts_default?(member, default)
+          end
+        end
+
+        def member_accepts_default?(member, default)
+          case member[:type]
+          when 'integer' then default.is_a?(Integer)
+          when 'number'  then default.is_a?(Numeric)
+          when 'boolean' then [true, false].include?(default)
+          when 'string'  then default.is_a?(String) || default.is_a?(Symbol)
+          when 'array'   then array_member_accepts?(member, default)
+          when 'object'  then default.is_a?(Hash)
+          end
+        end
+
+        def array_member_accepts?(member, default)
+          return false unless default.is_a?(Array)
+          return true if default.empty?
+
+          item_type = member.dig(:items, :type)
+          default.all? { |element| openapi_type_accepts?(item_type, element) }
+        end
+
+        def openapi_type_accepts?(openapi_type, value)
+          case openapi_type
+          when 'integer' then value.is_a?(Integer)
+          when 'number'  then value.is_a?(Numeric)
+          when 'boolean' then [true, false].include?(value)
+          when 'string'  then value.is_a?(String) || value.is_a?(Symbol)
+          else true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/converters/entity_converter.rb

@@ -175,12 +175,13 @@ module Gitlab
         end
 
         def build_one_of_property(types, documentation, default_value)
-          {
-            oneOf: types.map { |type| build_type_schema(type, documentation) },
+          members = types.map { |type| build_type_schema(type, documentation) }
+
+          TypeResolver.union_schema(members).merge(
             description: documentation[:desc],
             default: default_value,
             example: documentation[:example]
-          }
+          )
         end
 
         def build_single_type_property(type, documentation, default_value)

data/lib/gitlab/grape_openapi/converters/media_type_resolver.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      # Maps the media types a route declares via `produces` to the OpenAPI
+      # schema describing that response body.
+      #
+      # Media types the gem cannot describe resolve to `nil` so callers skip
+      # them instead of guessing.
+      class MediaTypeResolver
+        BINARY_SCHEMA = { type: 'string', format: 'binary' }.freeze
+        TEXT_SCHEMA = { type: 'string' }.freeze
+
+        OCTET_STREAM_MEDIA_TYPE = 'application/octet-stream'
+
+        BINARY_MEDIA_TYPES = [
+          'application/gzip',
+          OCTET_STREAM_MEDIA_TYPE,
+          'application/x-tar'
+        ].freeze
+
+        TEXT_MEDIA_TYPES = %w[application/yaml].freeze
+
+        TEXT_PREFIX = 'text/'
+
+        class << self
+          # `produces` accepts a bare String as well as an Array, and a declared
+          # type may carry parameters (`text/csv; charset=utf-8`) which are not
+          # part of an OpenAPI content key.
+          #
+          # Downcased because type and subtype are case-insensitive (RFC 6838),
+          # so the tables below can match on one spelling and the emitted content
+          # key stays canonical.
+          def normalize(declaration)
+            Array(declaration).filter_map do |media_type|
+              normalized = media_type.to_s.split(';').first&.strip&.downcase
+              normalized unless normalized.nil? || normalized.empty?
+            end.uniq
+          end
+
+          # `application/json` is handled by the entity `$ref` path
+          #  unrecognized types return nil rather than guessing the type
+          def schema_for(media_type)
+            return BINARY_SCHEMA if BINARY_MEDIA_TYPES.include?(media_type)
+            return TEXT_SCHEMA if TEXT_MEDIA_TYPES.include?(media_type) || media_type.start_with?(TEXT_PREFIX)
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/converters/operation_converter.rb

@@ -214,15 +214,12 @@ module Gitlab
         end
 
         def normalized_path
-          @normalized_path ||= path_override || normalize_path_pattern.gsub('{version}', config.api_version)
+          @normalized_path ||= path_override || normalize_path_pattern
         end
 
         def normalize_path_pattern
-          path = pattern.origin
-          path
-            .gsub(/\(\.:format\)$/, '')
+          NormalizedPath.new(pattern.origin).to_s
             .gsub(/[()\\]/, '')
-            .gsub(/:\w+/) { |match| "{#{match[1..]}}" }
             .gsub('{version}', config.api_version)
         end
 

data/lib/gitlab/grape_openapi/converters/parameter_converter.rb

@@ -5,7 +5,7 @@ module Gitlab
     module Converters
       class ParameterConverter
         include CoercerResolver
-        include Concerns::Serializable
+        include Concerns::ConstraintApplier
         include Concerns::LimitResolver
         include Concerns::FailFastAnnotatable
         include Concerns::RegexConverter
@@ -24,9 +24,7 @@ module Gitlab
         end
 
         def in_value
-          # Strip only the :version path segment (not substrings like :version_id or :package_version),
-          # then match the param name as a complete segment bounded by / . ( ) or end-of-string.
-          route.path.gsub('/:version/', '/').match?(%r{/:#{Regexp.escape(name)}([/.()]|$)}) ? 'path' : 'query'
+          path_parameter_names.include?(name.to_s) ? 'path' : 'query'
         end
 
         def example
@@ -61,6 +59,8 @@ module Gitlab
 
           apply_allow_blank(built_schema)
           apply_limit!(built_schema, validations)
+          apply_array_enum!(built_schema, options[:values])
+          apply_default!(built_schema, options[:default], example: example)
           built_schema
         end
 
@@ -72,9 +72,12 @@ module Gitlab
         def build_union_schema(object_type)
           types = object_type[1..-2].split(", ")
           members = types.map { |type| TypeResolver.resolve_union_member(type) }
+          schema = TypeResolver.union_schema(members)
+          members = schema.values.first
+          # Unlike `default:`, enum stays inline: it needs per-member type dispatch
+          # (coercing values to each member's type) that a generic post-step cannot do.
           apply_union_enum!(members)
-          apply_union_default!(members)
-          { oneOf: members }
+          schema
         end
 
         def build_range_schema(object_type)
@@ -83,14 +86,12 @@ module Gitlab
 
           schema[:minimum] = range.begin if range.begin
           schema[:maximum] = range.end if range.end
-          schema[:default] = options[:default] if options[:default] && serializable?(options[:default])
           schema
         end
 
         def build_enum_schema(object_type)
           schema = { type: object_type }
           schema[:enum] = options[:values] unless options[:values].is_a?(Proc)
-          schema[:default] = options[:default] if options[:default] && serializable?(options[:default])
           schema
         end
 
@@ -102,15 +103,6 @@ module Gitlab
         def build_basic_schema(object_type, object_format)
           schema = { type: object_type }
           schema[:format] = object_format if object_format
-          if options[:default] && serializable?(options[:default])
-            schema[:default] = options[:default]
-          elsif options[:default] &&
-              defined?(ActiveSupport::TimeWithZone) &&
-              options[:default].is_a?(ActiveSupport::TimeWithZone)
-            serialized_default = time_serializer.serialize(options[:default], example: example)
-            schema[:default] = serialized_default if serialized_default
-          end
-
           add_regex_validations!(schema)
           schema
         end
@@ -140,12 +132,15 @@ module Gitlab
           # GET and DELETE requests don't have request bodies, so all their parameters are included.
           method = route.request_method
           return nil if method != 'GET' && method != 'DELETE' && in_value != 'path'
+          return nil if options.dig(:documentation, :hidden)
 
           annotated = options.dup
           if options[:desc] && fail_fast_in_validations?(validations)
             annotated[:desc] = annotate_fail_fast(options[:desc])
           end
 
+          annotated[:desc] ||= route_param_desc
+
           param = Gitlab::GrapeOpenapi::Models::Parameter.new(
             name,
             options: annotated,
@@ -163,6 +158,18 @@ module Gitlab
 
         private
 
+        def path_parameter_names
+          @path_parameter_names ||= NormalizedPath.new(route.origin).path_parameter_names
+        end
+
+        # Only path parameters can come from a `route_param`, and a same-named query
+        # parameter must not pick its description up.
+        def route_param_desc
+          return unless in_value == 'path'
+
+          GrapeCompat.route_param_desc(route, name)
+        end
+
         def time_serializer
           @time_serializer ||= Serializers::Time.new
         end
@@ -188,59 +195,27 @@ module Gitlab
           end
         end
 
-        # When a union (oneOf) schema has a `default:`, attach it to every member
-        # whose schema can accept the default value. For arrays this includes
-        # checking the items type so `[1, 2]` lands on `items: { type: integer }`
-        # but not on `items: { type: string }`. Empty arrays are type-agnostic
-        # and attach to all array members.
-        def apply_union_default!(members)
-          default = options[:default]
-          return unless default && serializable?(default)
-
-          members.each do |member|
-            member[:default] = default if member_accepts_default?(member, default)
-          end
-        end
-
-        def member_accepts_default?(member, default)
-          case member[:type]
-          when 'integer' then default.is_a?(Integer)
-          when 'number'  then default.is_a?(Numeric)
-          when 'boolean' then [true, false].include?(default)
-          when 'string'  then default.is_a?(String) || default.is_a?(Symbol)
-          when 'array'   then array_member_accepts?(member, default)
-          when 'object'  then default.is_a?(Hash)
+        # Checked before super because serializable? returns false for TimeWithZone.
+        def resolve_default(default, example: nil)
+          if defined?(ActiveSupport::TimeWithZone) && default.is_a?(ActiveSupport::TimeWithZone)
+            return time_serializer.serialize(default, example: example)
           end
-        end
 
-        def array_member_accepts?(member, default)
-          return false unless default.is_a?(Array)
-          return true if default.empty?
-
-          item_type = member.dig(:items, :type)
-          default.all? { |element| openapi_type_accepts?(item_type, element) }
-        end
-
-        def openapi_type_accepts?(openapi_type, value)
-          case openapi_type
-          when 'integer' then value.is_a?(Integer)
-          when 'number'  then value.is_a?(Numeric)
-          when 'boolean' then [true, false].include?(value)
-          when 'string'  then value.is_a?(String) || value.is_a?(Symbol)
-          else true
-          end
+          super
         end
 
         # allow_blank defaults to true
         # when `allow_blank: false` for a string type minLength should be set to 1
         # when param is required and values option used, the param is not nullable
         def apply_allow_blank(schema)
+          union_members = schema[:oneOf] || schema[:anyOf]
+
           if options[:allow_blank] == false || (options[:required] && options[:values])
             schema[:minLength] = 1 if schema[:type] == 'string'
           elsif in_value != 'path'
             # path parameters are never nullable because they are required URL segments
-            if schema[:oneOf]
-              schema[:oneOf].each { |s| s[:nullable] = true }
+            if union_members
+              union_members.each { |s| s[:nullable] = true }
             else
               schema[:nullable] = true
             end

data/lib/gitlab/grape_openapi/converters/path_converter.rb

@@ -11,7 +11,14 @@ module Gitlab
         RESPONSE_DECLARATIONS = %i[entity success].freeze
 
         # A Grape optional path segment: a parenthesised group, e.g. `(/:id)`.
-        OPTIONAL_SEGMENT = /\(([^()]*)\)/
+        # A backslash-escaped paren is a literal character, not a group - OData
+        # routes use them, e.g. `nuget/v2/Packages\(Id='*package_name'\)`.
+        OPTIONAL_SEGMENT = /(?<!\\)\(([^()]*)(?<!\\)\)/
+
+        # The counterpart of OPTIONAL_SEGMENT: the parenthesis is a literal URL
+        # character and only the backslash is Grape pattern syntax, so the escape
+        # is dropped once optional segments have been resolved.
+        ESCAPED_PAREN = /\\([()])/
 
         # Optional path segment variants are each represented in the OpenAPI spec as a unique path.
         PathVariant = Struct.new(:key, :path_override, :removed_params)
@@ -77,20 +84,22 @@ module Gitlab
         end
 
         def skip_route?(route)
-          method = extract_method(route)
-          path = normalize_path(route)
-
           # Hidden routes (declared with `hidden true`) must be skipped before
           # OperationConverter runs. Otherwise it pollutes the shared schema and
           # request-body registries with entries that no emitted operation references,
           # surfacing as `no-unused-components` warnings under `components.schemas`.
           return true if hidden?(route)
 
-          # Grape registers catch-all routes with HTTP method * (matches any method) and
-          # paths containing *path (wildcard segments). Neither is valid OpenAPI: * isn't
-          # an HTTP method, and *path isn't a valid path segment. These are internal
-          # Grape routing artifacts, not actual API endpoints.
-          method == '*' || path.include?('*')
+          # Grape's catch-all (`route :any, '*path'`) is an internal routing artifact,
+          # not an API endpoint, and * isn't a valid HTTP method. Grape itself
+          # discriminates it by request method - see `collect_route_config_per_pattern`
+          # in `grape/api/instance.rb` - so match on the method alone.
+          #
+          # Do NOT also skip paths containing `*`. Splat segments are declared by
+          # developers for path segments that may contain slashes (`*module_name`,
+          # `*package_name`), and they are real endpoints. NormalizedPath renders them
+          # as ordinary `{name}` placeholders. See issue #22.
+          extract_method(route) == '*'
         end
 
         def hidden?(route)
@@ -98,12 +107,7 @@ module Gitlab
         end
 
         def normalize_path(route)
-          path = route.pattern.origin
-
-          path
-            .gsub(/\(\.:format\)$/, '')
-            .gsub(/:\w+/) { |match| "{#{match[1..]}}" }
-            .gsub('{version}', config.api_version)
+          NormalizedPath.new(route.pattern.origin).to_s.gsub('{version}', config.api_version)
         end
 
         def grouping_key(route)
@@ -136,18 +140,28 @@ module Gitlab
         # keys: a collapsed variant (segment and param removed entirely) and an
         # expanded variant (param present, rendered as a required path param).
         # Routes without such a segment yield a single, unchanged variant.
+        #
+        # Both variants resolve *every* optional group, not just the
+        # param-bearing one, because a route can put the separator in a group of
+        # its own: `releases/permalink/latest(/)(*suffix_path)` needs the `(/)`
+        # dropped alongside the param and inlined alongside it, or the expanded
+        # key would read `latest(/){suffix_path}` and match no real URL.
+        #
+        # Every emitted key drops the backslash of an escaped parenthesis, which
+        # can only happen once optional segments are resolved: until then it is
+        # the escape that tells a literal parenthesis apart from a group.
         def path_variants(path_key, route)
           param_groups = path_key.scan(OPTIONAL_SEGMENT).flatten.select { |inner| inner.match?(/\{\w+\}/) }
 
           raise MultipleOptionalSegmentsError, multi_segment_message(route, path_key) if param_groups.length > 1
 
           inner = param_groups.first
-          return [PathVariant.new(path_key, nil, [])] if inner.nil?
+          return [PathVariant.new(unescape_parens(path_key), nil, [])] if inner.nil?
 
           removed = inner.scan(/\{(\w+)\}/).flatten
-          collapsed = path_key.sub("(#{inner})", '').gsub(%r{//+}, '/').delete_suffix('/')
+          collapsed = unescape_parens(squeeze_slashes(path_key.gsub(OPTIONAL_SEGMENT, '')).delete_suffix('/'))
           collapsed = '/' if collapsed.empty?
-          expanded = path_key.sub("(#{inner})", inner).gsub(%r{//+}, '/')
+          expanded = unescape_parens(squeeze_slashes(path_key.gsub(OPTIONAL_SEGMENT) { Regexp.last_match(1) }))
 
           [
             PathVariant.new(collapsed, collapsed, removed),
@@ -155,6 +169,14 @@ module Gitlab
           ]
         end
 
+        def squeeze_slashes(path)
+          path.gsub(%r{//+}, '/')
+        end
+
+        def unescape_parens(path)
+          path.gsub(ESCAPED_PAREN) { Regexp.last_match(1) }
+        end
+
         def multi_segment_message(route, path_key)
           "Route '#{extract_method(route)} #{path_key}' declares more than one optional path segment " \
             "with a named parameter. gitlab-grape-openapi supports at most one optional segment per route " \

data/lib/gitlab/grape_openapi/converters/response_converter.rb

@@ -4,6 +4,10 @@ module Gitlab
   module GrapeOpenapi
     module Converters
       class ResponseConverter
+        # RFC 9110 forbids a body on these, so a declared media type cannot
+        # describe one.
+        BODYLESS_STATUS_CODES = %w[204 304].freeze
+
         def initialize(route, schema_registry)
           @route = route
           @schema_registry = schema_registry
@@ -19,14 +23,15 @@ module Gitlab
         private
 
         def extract_success_response
-          entity_definition = @route.options[:entity] || @route.options[:success]
+          entity_definition = success_definition
 
           case entity_definition
           when nil
-            success_code = infer_success_code
+            success_code = infer_success_code(with_body: declared_body?)
             add_simple_response(
               status_code: success_code,
-              description: http_status_text(success_code)
+              description: http_status_text(success_code),
+              content: declared_content
             )
           when Class
             process_class_entity(entity_definition)
@@ -46,10 +51,11 @@ module Gitlab
               entity_class: entity_class
             )
           else
-            success_code = infer_success_code
+            success_code = infer_success_code(with_body: declared_body?)
             add_simple_response(
               status_code: success_code,
-              description: http_status_text(success_code)
+              description: http_status_text(success_code),
+              content: declared_content
             )
           end
         end
@@ -65,10 +71,11 @@ module Gitlab
               examples: entity_hash[:examples]
             )
           else
-            status_code = entity_hash[:code] || infer_success_code
+            status_code = entity_hash[:code] || infer_success_code(with_body: declared_body?)
             add_simple_response(
               status_code: status_code,
-              description: entity_hash[:message] || http_status_text(status_code)
+              description: entity_hash[:message] || http_status_text(status_code),
+              content: declared_content
             )
           end
         end
@@ -95,10 +102,11 @@ module Gitlab
               examples: definition[:examples]
             )
           else
-            status_code = definition[:code] || infer_success_code
+            status_code = definition[:code] || infer_success_code(with_body: declared_body?)
             add_simple_response(
               status_code: status_code,
-              description: definition[:message] || http_status_text(status_code)
+              description: definition[:message] || http_status_text(status_code),
+              content: declared_content
             )
           end
         end
@@ -136,7 +144,9 @@ module Gitlab
           @responses[response.status_code] = response.to_h(@schema_registry)
         end
 
-        def add_simple_response(status_code:, description:)
+        # `content` is only ever passed for the success response, so failure
+        # responses stay JSON.
+        def add_simple_response(status_code:, description:, content: nil)
           key = status_code.to_s
 
           # `http_codes` (processed by `extract_failure_responses`) may include
@@ -148,7 +158,57 @@ module Gitlab
             @responses[key][:description] = description
           else
             @responses[key] = { description: description }
+            @responses[key][:content] = content if content && BODYLESS_STATUS_CODES.exclude?(key)
+          end
+        end
+
+        # Whether the route describes a body, which decides between 200 and 204
+        # for a DELETE.
+        def declared_body?
+          !declared_content.nil?
+        end
+
+        # The content map for a response is described with `produces` (or
+        # `success File`) rather than an entity. `nil` when the route declares
+        # nothing the gem can describe.
+        def declared_content
+          return @declared_content if defined?(@declared_content)
+
+          @declared_content = build_declared_content
+        end
+
+        # If there is no schema for the declared type it is dropped as guessing
+        # would misdescribe it. See MediaTypeResolver for the mapping.
+        def build_declared_content
+          content = declared_media_types.each_with_object({}) do |media_type, acc|
+            schema = MediaTypeResolver.schema_for(media_type)
+            acc[media_type] = { schema: schema } if schema
           end
+
+          content unless content.empty?
+        end
+
+        # An explicit `produces` overrides `success File`, matching grape-swagger existing behaviour.
+        def declared_media_types
+          produces = MediaTypeResolver.normalize(@route.settings.dig(:description, :produces))
+          return produces if produces.any?
+          return [] unless file_response?(success_definition)
+
+          [MediaTypeResolver::OCTET_STREAM_MEDIA_TYPE]
+        end
+
+        # Recognizes `success File` in any of its shapes. Compared by name so if `File`
+        # is passed as a String it matches. Aligns with grape-swagger's `file_response?`
+        def file_response?(definition)
+          case definition
+          when Array then definition.any? { |item| file_response?(item) }
+          when Hash then file_response?(definition[:model])
+          else definition.to_s == 'File'
+          end
+        end
+
+        def success_definition
+          @route.options[:entity] || @route.options[:success]
         end
 
         # 204 means "No Content", so it only applies when the response has no
@@ -174,10 +234,9 @@ module Gitlab
         end
 
         def path_has_resource_parameters?
-          path = @route.path
-            .gsub('.:format', '')
-            .gsub(':version', '')
-          path.include?(':')
+          # Splat segments count: `/packages/npm/*package_name` addresses a resource
+          # just as `/packages/:id` does, so it earns the same inferred 404.
+          NormalizedPath.new(@route.origin).path_parameter_names.any?
         end
 
         def http_status_text(code)

data/lib/gitlab/grape_openapi/converters/type_resolver.rb

@@ -66,9 +66,25 @@ module Gitlab
             item_type = type[1..-2]
             { type: 'array', items: { type: resolve_type(item_type) || 'string' } }
           else
-            { type: resolve_type(type) || 'string' }
+            member = { type: resolve_type(type) || 'string' }
+            format = resolve_format(nil, type)
+            member[:format] = format if format
+            member
           end
         end
+
+        # `oneOf` means "valid against exactly one". Members that differ only by `format`
+        # are indistinguishable to a validator, because `format` annotates rather than
+        # constrains, so nothing could satisfy it and `anyOf` ("at least one") is the
+        # accurate keyword. Keep `oneOf` everywhere else: it is the stricter of the two
+        # and says more about the parameter.
+        def self.union_schema(members)
+          members = members.uniq
+          asserted = members.map { |member| member.except(:format) }
+          keyword = asserted.uniq.size == members.size ? :oneOf : :anyOf
+
+          { keyword => members }
+        end
       end
     end
   end

data/lib/gitlab/grape_openapi/grape_compat.rb

@@ -25,6 +25,22 @@ module Gitlab
           end
         end
 
+        # The `desc:` an author writes on `route_param`. Grape forwards only `type:` into
+        # the `requires` it declares internally and discards the rest, so the description
+        # never reaches the route's params. It survives on the namespace whose space is
+        # the `:placeholder` segment. Searched innermost first.
+        def route_param_desc(route, name)
+          return unless route.app.respond_to?(:inheritable_setting)
+
+          namespaces = route.app.inheritable_setting&.namespace_stackable&.[](:namespace) || []
+          namespace = namespaces.reverse.find { |candidate| candidate.space.to_s == ":#{name}" }
+          options = namespace&.options
+          return unless options.is_a?(Hash)
+
+          desc = options[:desc]
+          desc if desc.is_a?(String)
+        end
+
         private
 
         def normalize(validation)

data/lib/gitlab/grape_openapi/models/request_body/parameter_schema.rb

@@ -6,7 +6,7 @@ module Gitlab
       module RequestBody
         class ParameterSchema
           include Converters::CoercerResolver
-          include Concerns::Serializable
+          include Concerns::ConstraintApplier
           include Concerns::LimitResolver
           include Concerns::FailFastAnnotatable
           include Concerns::RegexConverter
@@ -31,6 +31,8 @@ module Gitlab
 
             apply_allow_blank(built_schema)
             apply_limit!(built_schema, validations)
+            apply_array_enum!(built_schema, param_options[:values])
+            apply_default!(built_schema, param_options[:default])
             built_schema
           end
 
@@ -109,7 +111,10 @@ module Gitlab
 
           def build_union_type_schema
             types = param_options[:type][1..-2].split(", ")
-            { oneOf: types.map { |type| Converters::TypeResolver.resolve_union_member(type) } }
+            members = types.map { |type| Converters::TypeResolver.resolve_union_member(type) }
+            schema = Converters::TypeResolver.union_schema(members)
+            schema[:description] = annotated_description if param_options[:desc]
+            schema
           end
 
           def build_range_schema(object_type)
@@ -117,10 +122,6 @@ module Gitlab
             schema = { type: object_type }
             schema[:minimum] = range.begin if range.begin
             schema[:maximum] = range.end if range.end
-            if param_options[:default] && serializable?(param_options[:default])
-              schema[:default] = param_options[:default]
-            end
-
             schema[:description] = annotated_description if param_options[:desc]
             schema
           end
@@ -128,10 +129,6 @@ module Gitlab
           def build_enum_schema(object_type)
             schema = { type: object_type }
             schema[:enum] = param_options[:values] unless param_options[:values].is_a?(Proc)
-            if param_options[:default] && serializable?(param_options[:default])
-              schema[:default] = param_options[:default]
-            end
-
             schema[:description] = annotated_description if param_options[:desc]
             schema
           end
@@ -202,10 +199,6 @@ module Gitlab
           def build_basic_schema(object_type, object_format)
             schema = { type: object_type }
             schema[:format] = object_format if object_format
-            if param_options[:default] && serializable?(param_options[:default])
-              schema[:default] = param_options[:default]
-            end
-
             schema[:description] = annotated_description if param_options[:desc]
 
             if param_options.dig(:documentation, :example)
@@ -230,10 +223,12 @@ module Gitlab
           end
 
           def apply_allow_blank(schema)
+            union_members = schema[:oneOf] || schema[:anyOf]
+
             if param_options[:allow_blank] == false || (param_options[:required] && param_options[:values])
               schema[:minLength] = 1 if schema[:type] == 'string'
-            elsif schema[:oneOf]
-              schema[:oneOf].each { |s| s[:nullable] = true }
+            elsif union_members
+              union_members.each { |s| s[:nullable] = true }
             else
               schema[:nullable] = true
             end

data/lib/gitlab/grape_openapi/models/request_body/parameters.rb

@@ -14,7 +14,7 @@ module Gitlab
 
           def extract
             body_params = params.reject do |key, _|
-              path_with_params.include?("{#{key}}")
+              path_with_params.include?("{#{key}}") || hidden?(key)
             end
 
             restructure_nested_params(body_params)
@@ -22,10 +22,22 @@ module Gitlab
 
           private
 
+          # `documentation: { hidden: true }` marks a param the author does not want
+          # documented. Params nested below it, in bracket notation, go with it.
+          def hidden?(key)
+            key_str = key.to_s
+
+            hidden_keys.any? { |hidden| key_str == hidden || key_str.start_with?("#{hidden}[") }
+          end
+
+          def hidden_keys
+            @hidden_keys ||= params.filter_map do |key, param_options|
+              key.to_s if param_options.is_a?(Hash) && param_options.dig(:documentation, :hidden)
+            end
+          end
+
           def path_with_params
-            @path_with_params ||= route.origin
-              .gsub(/\(\.:format\)$/, '')
-              .gsub(/:\w+/) { |match| "{#{match[1..]}}" }
+            @path_with_params ||= NormalizedPath.new(route.origin).to_s
           end
 
           def restructure_nested_params(body_params)

data/lib/gitlab/grape_openapi/normalized_path.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    # A Grape route pattern rendered as an OpenAPI path template.
+    #
+    # Grape spells path placeholders two ways: `:name` matches a single segment,
+    # and `*name` (a splat) matches one or more segments, so its value may contain
+    # slashes. OpenAPI 3.0 has no splat syntax, so both collapse to `{name}`.
+    #
+    # The splat mapping is lossy - `{name}` implies a single segment - but the
+    # endpoint is documented, which is strictly better than omitting it. Do not
+    # "fix" this by dropping splat routes: that is the bug in issue #22, which
+    # silently removed the entire package registry surface from the spec.
+    class NormalizedPath
+      # Grape appends the format suffix to `route.path`, not to `route.pattern.origin`,
+      # so this only strips a suffix an author wrote into the pattern by hand. Without
+      # it, a declared `format` param would be mistaken for a path parameter.
+      FORMAT_SUFFIX = /\(\.:format\)$/
+
+      PLACEHOLDER = /[:*](\w+)/
+      NORMALIZED_PLACEHOLDER = /\{(\w+)\}/
+
+      # The API version is substituted away with the configured value before a path
+      # is emitted, so it never surfaces as a path parameter.
+      API_VERSION_PLACEHOLDER = 'version'
+
+      attr_reader :origin
+
+      # Takes a `route.pattern.origin` - the pattern as the author declared it.
+      # Do not pass `route.path`: Grape rewrites that one, appending the format
+      # suffix and turning a trailing `*path` into `?*path`.
+      def initialize(origin)
+        @origin = origin
+      end
+
+      def to_s
+        @to_s ||= origin
+          .sub(FORMAT_SUFFIX, '')
+          .gsub(PLACEHOLDER) { "{#{Regexp.last_match(1)}}" }
+      end
+
+      def placeholder_names
+        # Scanning whole `{name}` placeholders sidesteps the boundary problem a regex
+        # over the raw pattern has: real routes introduce a placeholder after `/`,
+        # `(`, `)` and `'` - `(*path`, `):file_name`, `Id='*package_name'` - so there
+        # is no single delimiter to anchor on.
+        @placeholder_names ||= to_s.scan(NORMALIZED_PLACEHOLDER).flatten
+      end
+
+      def path_parameter_names
+        placeholder_names - [API_VERSION_PLACEHOLDER]
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/request_body_registry.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'digest'
+require 'openssl'
 
 module Gitlab
   module GrapeOpenapi

data/lib/gitlab/grape_openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module GrapeOpenapi
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/gitlab-grape-openapi.rb

@@ -7,9 +7,11 @@ require_relative "gitlab/grape_openapi/generator"
 require_relative "gitlab/grape_openapi/schema_registry"
 require_relative "gitlab/grape_openapi/request_body_registry"
 require_relative "gitlab/grape_openapi/tag_registry"
+require_relative "gitlab/grape_openapi/normalized_path"
 
 # Concerns
 require_relative "gitlab/grape_openapi/concerns/serializable"
+require_relative "gitlab/grape_openapi/concerns/constraint_applier"
 require_relative "gitlab/grape_openapi/concerns/limit_resolver"
 require_relative "gitlab/grape_openapi/concerns/fail_fast_annotatable"
 require_relative "gitlab/grape_openapi/concerns/regex_converter"
@@ -20,6 +22,7 @@ require_relative "gitlab/grape_openapi/serializers/time"
 # Converters
 require_relative "gitlab/grape_openapi/converters/coercer_resolver"
 require_relative "gitlab/grape_openapi/converters/entity_converter"
+require_relative "gitlab/grape_openapi/converters/media_type_resolver"
 require_relative "gitlab/grape_openapi/converters/type_resolver"
 require_relative "gitlab/grape_openapi/converters/tag_converter"
 require_relative "gitlab/grape_openapi/converters/operation_converter"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-grape-openapi
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - group::api
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -139,6 +139,7 @@ files:
 - LICENSE
 - README.md
 - lib/gitlab-grape-openapi.rb
+- lib/gitlab/grape_openapi/concerns/constraint_applier.rb
 - lib/gitlab/grape_openapi/concerns/fail_fast_annotatable.rb
 - lib/gitlab/grape_openapi/concerns/limit_resolver.rb
 - lib/gitlab/grape_openapi/concerns/regex_converter.rb
@@ -146,6 +147,7 @@ files:
 - lib/gitlab/grape_openapi/configuration.rb
 - lib/gitlab/grape_openapi/converters/coercer_resolver.rb
 - lib/gitlab/grape_openapi/converters/entity_converter.rb
+- lib/gitlab/grape_openapi/converters/media_type_resolver.rb
 - lib/gitlab/grape_openapi/converters/operation_converter.rb
 - lib/gitlab/grape_openapi/converters/parameter_converter.rb
 - lib/gitlab/grape_openapi/converters/path_converter.rb
@@ -167,6 +169,7 @@ files:
 - lib/gitlab/grape_openapi/models/server.rb
 - lib/gitlab/grape_openapi/models/server_variable.rb
 - lib/gitlab/grape_openapi/models/tag.rb
+- lib/gitlab/grape_openapi/normalized_path.rb
 - lib/gitlab/grape_openapi/request_body_registry.rb
 - lib/gitlab/grape_openapi/schema_registry.rb
 - lib/gitlab/grape_openapi/serializers/time.rb