gitlab-grape-openapi 0.3.0 → 0.5.0

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

@@ -5,10 +5,11 @@ module Gitlab
     module Converters
       class ParameterConverter
         include CoercerResolver
-        include Concerns::Serializable
+        include Concerns::ConstraintApplier
         include Concerns::LimitResolver
         include Concerns::FailFastAnnotatable
         include Concerns::RegexConverter
+        include Concerns::Nullability
 
         attr_reader :name, :options, :validations, :route
 
@@ -24,9 +25,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
@@ -59,8 +58,10 @@ module Gitlab
                            build_basic_schema(object_type, object_format)
                          end
 
-          apply_allow_blank(built_schema)
+          apply_nullability!(built_schema, options, in_value: in_value)
           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 +73,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 +87,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 +104,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 +133,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 +159,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,63 +196,13 @@ 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)
+        # 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 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
-
-        # 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)
-          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 }
-            else
-              schema[:nullable] = true
-            end
-          end
+          super
         end
       end
     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/request_body_converter.rb

@@ -50,6 +50,8 @@ module Gitlab
             required_params << key.to_s if param_options[:required]
           end
 
+          annotate_cross_field_constraints!(properties)
+
           schema = {
             type: 'object',
             properties: properties
@@ -68,6 +70,43 @@ module Gitlab
           }
         end
 
+        # Documents cross-field constraints (mutually_exclusive, ...) in each
+        # affected property's description. OpenAPI has no cross-property keyword
+        # and Scalar does not render JSON Schema `not` so the validation constraint
+        # is expressed in prose.
+        def annotate_cross_field_constraints!(properties)
+          resolver = CrossFieldValidationResolver.new(route, properties.keys)
+
+          resolver.notes.each do |name, note|
+            property = properties[name]
+            next unless property
+
+            property[:description] = CrossFieldValidationResolver.append_note(property[:description], note)
+          end
+
+          warn_skipped_cross_field_constraints(resolver.skipped)
+        end
+
+        # Warns about a constraint we cannot document yet, because a member of the
+        # group is not a property of this body. Usually the group is nested inside
+        # an object property - GET/DELETE flatten such params into the query and
+        # document them, POST/PUT/PATCH bodies keep the nesting - but a member
+        # dropped from the body for another reason (a path param, or one hidden
+        # with `documentation: { hidden: true }`) lands here too, hence the wording.
+        def warn_skipped_cross_field_constraints(skipped)
+          return unless config.warnings
+
+          path = NormalizedPath.new(route.pattern.origin).to_display_path(config.api_version)
+          skipped.each do |group|
+            warn "[gitlab-grape-openapi] skipped cross-field constraint: " \
+              "#{route_method} #{path} params=#{group.join(',')} (not a top-level body property)"
+          end
+        end
+
+        def config
+          @config ||= Gitlab::GrapeOpenapi.configuration
+        end
+
         def content_type(body_params)
           custom_content_type = extract_consumes_content_type
           return custom_content_type if custom_content_type

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

@@ -11,12 +11,8 @@ module Gitlab
     module GrapeCompat
       class << self
         # Declared validations for a single attribute, newest scope only.
-        #
-        # Reads `new_values` rather than `[]` or `route[:saved_validations]` on
-        # purpose: those also include validations inherited from parent scopes,
-        # which would change the generated output.
         def validations_for(route, attribute)
-          validations = route.app.inheritable_setting.namespace_stackable.new_values[:validations]
+          validations = declared_validations(route)
           return unless validations
 
           validations.filter_map do |validation|
@@ -25,10 +21,49 @@ module Gitlab
           end
         end
 
+        # Every declared validation for a route, normalized, newest scope only.
+        # Unlike `validations_for` this keeps group validators (mutually_exclusive
+        # and friends) whose `:attributes` span several params.
+        def all_validations(route)
+          validations = declared_validations(route)
+          return [] unless validations
+
+          validations.filter_map { |validation| normalize(validation) }
+        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
 
+        # The route's raw, un-normalized validation stack, and the only place this
+        # gem reaches into Grape for it.
+        #
+        # Reads `new_values` rather than `[]` or `route[:saved_validations]` on
+        # purpose: those also include validations inherited from parent scopes,
+        # which would change the generated output.
+        def declared_validations(route)
+          route.app.inheritable_setting.namespace_stackable.new_values[:validations]
+        end
+
         def normalize(validation)
-          return validation if validation.is_a?(Hash)
+          if validation.is_a?(Hash) # Grape < 3.2
+            # Do not mutate the author's own Hash; add the derived key on a copy.
+            return validation.merge(full_names: full_names_for(validation[:params_scope], validation[:attributes]))
+          end
 
           # Grape 3.2's ContractScopeValidator declares no attributes, so it maps
           # to no parameter.
@@ -41,9 +76,26 @@ module Gitlab
             # carry regexp patterns and limits. Switch to the reader if one is
             # added upstream.
             options: validation.instance_variable_get(:@options),
-            opts: { fail_fast: validation.fail_fast? }
+            opts: { fail_fast: validation.fail_fast? },
+            # Full bracketed paths (e.g. "filter[x]") for cross-field constraints
+            # in nested scopes; equal to the bare name at the root. No public
+            # reader for the scope on 3.2, hence the ivar.
+            full_names: full_names_for(validation.instance_variable_get(:@scope), validation.attrs)
           }
         end
+
+        # Maps each attribute to its full bracketed path via the param scope, so a
+        # nested `x` becomes "filter[x]" while a top-level `x` stays "x". Falls
+        # back to the bare name if the scope cannot resolve it.
+        def full_names_for(scope, attributes)
+          Array(attributes).map do |attribute|
+            if scope.respond_to?(:full_name)
+              scope.full_name(attribute).to_s
+            else
+              attribute.to_s
+            end
+          end
+        end
       end
     end
   end