gitlab-grape-openapi 0.3.0 → 0.5.0

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

@@ -6,10 +6,11 @@ module Gitlab
       module RequestBody
         class ParameterSchema
           include Converters::CoercerResolver
-          include Concerns::Serializable
+          include Concerns::ConstraintApplier
           include Concerns::LimitResolver
           include Concerns::FailFastAnnotatable
           include Concerns::RegexConverter
+          include Concerns::Nullability
 
           def initialize(route:, key:, param_options:)
             @route = route
@@ -29,8 +30,10 @@ module Gitlab
               built_schema = build_resolved_schema(object_type, object_format)
             end
 
-            apply_allow_blank(built_schema)
+            apply_nullability!(built_schema, param_options)
             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 +112,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 +123,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 +130,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 +200,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)
@@ -228,16 +222,6 @@ module Gitlab
           def validations_for(attribute)
             GrapeCompat.validations_for(route, attribute)
           end
-
-          def apply_allow_blank(schema)
-            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 }
-            else
-              schema[:nullable] = true
-            end
-          end
         end
       end
     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,68 @@
+# 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+)\}/
+
+      # Grape's optional-segment markup: the parentheses grouping an optional
+      # segment, and the backslashes escaping a literal parenthesis. Both are
+      # noise once a path is rendered for a human.
+      OPTIONAL_SEGMENT_MARKUP = /[()\\]/
+
+      # 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
+
+      # The path as shown to humans in emitted paths and warnings: placeholders
+      # collapsed (via `to_s`), optional-segment markup removed, and the API
+      # version substituted in for `{version}`.
+      def to_display_path(api_version)
+        to_s.gsub(OPTIONAL_SEGMENT_MARKUP, '').gsub("{#{API_VERSION_PLACEHOLDER}}", api_version)
+      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.5.0"
   end
 end

data/lib/gitlab-grape-openapi.rb

@@ -7,19 +7,24 @@ 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"
+require_relative "gitlab/grape_openapi/concerns/nullability"
 
 # Serializers
 require_relative "gitlab/grape_openapi/serializers/time"
 
 # Converters
 require_relative "gitlab/grape_openapi/converters/coercer_resolver"
+require_relative "gitlab/grape_openapi/converters/cross_field_validation_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.5.0
 platform: ruby
 authors:
 - group::api
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -139,13 +139,17 @@ 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/nullability.rb
 - lib/gitlab/grape_openapi/concerns/regex_converter.rb
 - lib/gitlab/grape_openapi/concerns/serializable.rb
 - lib/gitlab/grape_openapi/configuration.rb
 - lib/gitlab/grape_openapi/converters/coercer_resolver.rb
+- lib/gitlab/grape_openapi/converters/cross_field_validation_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 +171,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