gitlab-grape-openapi 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0abbc799f3af1d884ee9e543865658f3709007fe0cb09febea2792678c09d071
-  data.tar.gz: 815581f530dbedff8b9cd89135507640df91e58435f42a62c78bd1d213388d46
+  metadata.gz: 10a34008541dedbab4063d199bbdb94f2d669d94101be45af1023e362bf8c72f
+  data.tar.gz: ba640eb0b0553149b7776bd53afef9eee0c2cc5316dbb4917c44c2099b138d0e
 SHA512:
-  metadata.gz: 2574c73242cbbb597331b2919a05ced49beba5dbe733683d88cf90d1ae71d2e55ecffbc2443b399ad5d52e9dc74e53cee7360f3e998b1bc0e8cf7ae8c4603138
-  data.tar.gz: 2bcf5665113a86d6aee987a543fb101ce582bda2801498765a89ca5c42432b8da9d6461bafeb4cfea11f522cbf75ea77497b8ce580329c088ab0ca485007b795
+  metadata.gz: fd55dfbd2de53ec38abfd182f89d2dcbf2f03b916fbde38525dd8566c5984d134b21a9ff112123a7d2d9dbec0fc8077c8bf4a04d40117c902215e4a4cb6eb52b
+  data.tar.gz: 4ece03be3b48a4f4082539446d72ab4ac68b8cd0a022ee125f777c7196dd2aac73b154bc98f1518ac078da6b13b26a80c0a0a4dfabada8f220d461b507202e2c

data/README.md

@@ -88,22 +88,32 @@ Gitlab::GrapeOpenapi.configure do |config|
   config.annotations = {
     lifecycle: 'x-gitlab-lifecycle'
   }
+
+  # Cross-field groups larger than this are stated once on the endpoint
+  config.cross_field_group_limit = 30
+
+  # Endpoint wording for those, keyed by "METHOD /path"
+  config.cross_field_messages = {
+    'PUT /api/v4/application/settings' => 'At least one setting must be updated.'
+  }
 end
 ```
 
 ### Configuration Options
 
-| Option                 | Type                            | Default | Description                                                  |
-| ---------------------- | ------------------------------- | ------- | ------------------------------------------------------------ |
-| `info`                 | `Models::Info`                  | `nil`   | API metadata (title, description, version, terms of service) |
-| `api_prefix`           | `String`                        | `"api"` | URL prefix for API routes                                    |
-| `api_version`          | `String`                        | `"v1"`  | API version string                                           |
-| `servers`              | `Array<Models::Server>`         | `[]`    | Server definitions for the API                               |
-| `security_schemes`     | `Array<Models::SecurityScheme>` | `[]`    | Authentication/authorization schemes                         |
-| `excluded_api_classes` | `Array<String>`                 | `[]`    | API class names to exclude from generation                   |
-| `tag_overrides`        | `Hash`                          | `{}`    | Map of tag names to their display overrides                  |
-| `annotations`          | `Hash`                          | `{}`    | Map of Grape route settings to OpenAPI extension names       |
-| `warnings`             | `Boolean`                       | `false` | Emit stderr warnings for synthesized (undeclared) path params |
+| Option                 | Type                            | Default | Description                                                      |
+| ---------------------- | ------------------------------- | ------- | ---------------------------------------------------------------- |
+| `info`                 | `Models::Info`                  | `nil`   | API metadata (title, description, version, terms of service)     |
+| `api_prefix`           | `String`                        | `"api"` | URL prefix for API routes                                        |
+| `api_version`          | `String`                        | `"v1"`  | API version string                                               |
+| `servers`              | `Array<Models::Server>`         | `[]`    | Server definitions for the API                                   |
+| `security_schemes`     | `Array<Models::SecurityScheme>` | `[]`    | Authentication/authorization schemes                             |
+| `excluded_api_classes` | `Array<String>`                 | `[]`    | API class names to exclude from generation                       |
+| `tag_overrides`        | `Hash`                          | `{}`    | Map of tag names to their display overrides                      |
+| `annotations`          | `Hash`                          | `{}`    | Map of Grape route settings to OpenAPI extension names           |
+| `warnings`             | `Boolean`                       | `false` | Emit stderr warnings for synthesized params, skipped constraints |
+| `cross_field_group_limit` | `Integer`                    | `30`    | Cross-field groups larger than this are summarised on the endpoint |
+| `cross_field_messages` | `Hash`                          | `{}`    | Endpoint wording for summarised groups, keyed by `"METHOD /path"` |
 
 ### Annotations
 
@@ -186,9 +196,54 @@ Generator
 │   ├── ResponseConverter   - Converts endpoint responses
 │   └── RequestBodyConverter - Converts request bodies
 ├── MediaTypeResolver   - Maps declared media types to response schemas
-└── TypeResolver        - Maps Ruby/Grape types to OpenAPI types
+├── TypeResolver        - Maps Ruby/Grape types to OpenAPI types
+└── CrossFieldValidationResolver - Documents Grape cross-field validations in descriptions
 ```
 
+### Parameter constraints
+
+The gem documents Grape's cross-field param constraints by appending a note to
+each affected parameter's (or request-body property's) `description` — for both
+query/path params (`GET`/`DELETE`) and request-body params
+(`POST`/`PUT`/`PATCH`). Three constraints are supported:
+
+| Grape declaration | Note appended to every member |
+|-------------------|-------------------------------|
+| `mutually_exclusive :author_id, :author_username` | ``Mutually exclusive with `author_username`.`` |
+| `exactly_one_of :project_id, :project_path` | ``Exactly one of `project_id`, `project_path` must be provided.`` |
+| `at_least_one_of :assignee_id, :reviewer_id` | ``At least one of `assignee_id`, `reviewer_id` must be provided.`` |
+
+OpenAPI 3.0 has no cross-parameter constraint keyword, and the target renderer
+(Scalar) does not render JSON Schema `not`/`allOf`, so the constraint is stated
+in prose; Grape enforces it at runtime (HTTP 400). Members of these groups stay
+individually optional — the constraint binds the group, not any single param, so
+no `required` entry is emitted.
+
+They differ in how several declarations over one param are combined. Only
+`mutually_exclusive` is pairwise, so a param lists every partner in one note. The
+group constraints do not compose that way, so each declaration is stated as its
+own sentence: `at_least_one_of :a, :b` alongside `at_least_one_of :a, :c` forbids
+`b` alone, which the collapsed "At least one of `a`, `b`, `c`" would allow.
+
+A group large enough that naming every member becomes unreadable — GitLab's
+`PUT /api/v4/application/settings` declares `at_least_one_of` over 664 params — is
+not enumerated. The rule is stated once on the endpoint's own `description`
+instead, and its members keep their original descriptions. `cross_field_group_limit`
+sets the threshold; `cross_field_messages` supplies wording per endpoint, keyed by
+the same `"METHOD /path"` string the warnings print. Without an entry the gem uses
+a generic sentence and, with `warnings` enabled, names the endpoint so wording can
+be added.
+
+The gem reads the validation stack through `grape_compat`, so this works on both
+Grape 2.4 and 3.2. Each group is keyed by the full bracketed param path
+(`not[author_id]`) rather than the bare name. Because Grape flattens every nested
+param into the route's query params, a constraint nested inside a `Hash` *query*
+filter is documented the same as a top-level one. A constraint nested inside a
+request-body object property has no top-level property to attach to and is
+skipped; when `warnings` is enabled the gem logs one line per skipped group so it
+is visible in source. The remaining sibling constraint (`all_or_none_of`) is not
+yet supported.
+
 ### Registries
 
 - **SchemaRegistry** - Tracks converted entity schemas
@@ -198,8 +253,23 @@ Generator
 ### 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:
+declared with `success` / `entity`. Declaring the route as a collection wraps
+that `$ref` in a `type: array` / `items:` schema, so a collection endpoint is
+not published as a single object. Both of Grape's forms are honoured — inline
+in the declaration (`success code: 200, model: Entities::Tag, is_array: true`)
+and standalone in the `desc` block:
+
+```ruby
+desc 'List tags' do
+  success code: 200, model: Entities::Tag
+  is_array true
+end
+```
+
+An inline `is_array:` takes precedence over the standalone setting.
+
+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

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

@@ -16,7 +16,7 @@ module Gitlab
           return unless schema[:type] == 'array' && schema[:items].is_a?(Hash)
           return unless values.is_a?(Array)
 
-          schema[:items][:enum] = values
+          schema[:items][:enum] = stringify_symbols(values)
         end
 
         def apply_default!(schema, default, example: nil)
@@ -33,7 +33,7 @@ module Gitlab
         def resolve_default(default, example: nil) # rubocop:disable Lint/UnusedMethodArgument -- overridden
           return unless serializable?(default)
 
-          default
+          stringify_symbols(default)
         end
 
         # When a union (oneOf) schema has a `default:`, attach it to every member
@@ -45,7 +45,7 @@ module Gitlab
           return unless serializable?(default)
 
           members.each do |member|
-            member[:default] = default if member_accepts_default?(member, default)
+            member[:default] = stringify_symbols(default) if member_accepts_default?(member, default)
           end
         end
 

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Determines whether a param is nullable.
+#
+# Grape default behaviour sets nullability true for plain params.
+# Two declarations remove it: a `default:`, which Grape's
+# DefaultValidator substitutes for the null before the endpoint runs, and a path
+# parameter, which is a required URL segment.
+#
+# The `minLength: 1` branch is mutually exclusive with nullability and stays coupled
+# here deliberately: applying the two independently would mark every required enum
+# nullable.
+#
+# NOTE: `param_options[:allow_blank]` is always nil. Grape omits allow_blank from
+# route.params, so that clause is dead and only `required && values` fires.
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      module Nullability
+        private
+
+        def apply_nullability!(schema, param_options, in_value: nil)
+          if blank_rejected?(param_options)
+            schema[:minLength] = 1 if schema[:type] == 'string'
+          elsif nullable?(param_options, in_value)
+            mark_nullable!(schema)
+          end
+        end
+
+        def blank_rejected?(param_options)
+          param_options[:allow_blank] == false ||
+            (param_options[:required] && param_options[:values])
+        end
+
+        def nullable?(param_options, in_value)
+          return false if in_value == 'path'
+
+          param_options[:default].nil?
+        end
+
+        # Grape substitutes the default regardless of which union member matched, so
+        # nullability applies to every member or none.
+        def mark_nullable!(schema)
+          members = schema[:oneOf] || schema[:anyOf]
+          return members.each { |member| member[:nullable] = true } if members
+
+          schema[:nullable] = true
+        end
+      end
+    end
+  end
+end

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

@@ -13,6 +13,16 @@ module Gitlab
 
           true
         end
+
+        # Symbol maps to OpenAPI `string`, so Symbol values must become strings too.
+        # Otherwise a Symbol serializes as `:value` in YAML, which parsers read back as that string.
+        def stringify_symbols(value)
+          case value
+          when Symbol then value.to_s
+          when Array then value.map { |element| stringify_symbols(element) }
+          else value
+          end
+        end
       end
     end
   end

data/lib/gitlab/grape_openapi/configuration.rb

@@ -4,7 +4,8 @@ module Gitlab
   module GrapeOpenapi
     class Configuration
       attr_accessor :api_version, :api_prefix, :excluded_api_classes, :servers, :security_schemes, :info,
-        :tag_overrides, :annotations, :coercer_mappings, :warnings
+        :tag_overrides, :annotations, :coercer_mappings, :warnings,
+        :cross_field_group_limit, :cross_field_messages
 
       def initialize
         @api_prefix = "api"
@@ -19,6 +20,12 @@ module Gitlab
         @annotations = {}
         @coercer_mappings = {}
         @warnings = false
+
+        # Cross field validations
+        # Allow custom descriptions for endpoints whose groups of cross-validated
+        # params exceed cross_field_group_limit
+        @cross_field_group_limit = 30
+        @cross_field_messages = {}
       end
     end
   end

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

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# Documents Grape cross-field param validations by appending a note to each
+# affected parameter's / request-body property's description.
+#
+# OpenAPI 3.0 has no cross-parameter keyword and Scalar (the renderer) does not
+# render JSON Schema `not`/`allOf`, so these constraints are stated in prose;
+# Grape enforces them at runtime (HTTP 400).
+#
+# Each cross-field validator is a CONSTRAINTS entry pairing the validator class
+# names it carries across supported Grape versions (Grape 3.2 renamed one)
+# with a note strategy. A strategy receives every group of its kind found on the
+# route (each group an array of top-level attribute-name strings) and returns
+# `{ param => note }`.
+#
+# The validations read and the Grape 2.x/3.2 shape difference are isolated in
+# GrapeCompat.
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class CrossFieldValidationResolver
+        GROUP_SENTENCE = lambda do |lead|
+          lambda do |groups|
+            groups.each_with_object({}) do |group, result|
+              note = "#{lead} #{group.map { |name| "`#{name}`" }.join(', ')} must be provided."
+
+              group.each { |name| result[name] = append_note(result[name], note) }
+            end
+          end
+        end
+
+        MUTUALLY_EXCLUSIVE = {
+          classes: [
+            'Grape::Validations::Validators::MutualExclusionValidator',  # Grape < 3.2
+            'Grape::Validations::Validators::MutuallyExclusiveValidator' # Grape >= 3.2
+          ].freeze,
+          summary_format: 'At most one of %d related parameters may be provided.',
+          notes: lambda do |groups|
+            partners = Hash.new { |hash, key| hash[key] = [] }
+
+            groups.each do |group|
+              group.each do |name|
+                (group - [name]).each do |other|
+                  partners[name] << other unless partners[name].include?(other)
+                end
+              end
+            end
+
+            partners.transform_values do |others|
+              "Mutually exclusive with #{others.map { |name| "`#{name}`" }.join(', ')}."
+            end
+          end
+        }.freeze
+
+        EXACTLY_ONE_OF = {
+          classes: [
+            'Grape::Validations::Validators::ExactlyOneOfValidator' # Grape all versions
+          ].freeze,
+          summary_format: 'Exactly one of %d related parameters must be provided.',
+          notes: GROUP_SENTENCE.call('Exactly one of')
+        }.freeze
+
+        AT_LEAST_ONE_OF = {
+          classes: [
+            'Grape::Validations::Validators::AtLeastOneOfValidator' # Grape all versions
+          ].freeze,
+          summary_format: 'At least one of %d related parameters must be provided.',
+          notes: GROUP_SENTENCE.call('At least one of')
+        }.freeze
+
+        CONSTRAINTS = [MUTUALLY_EXCLUSIVE, EXACTLY_ONE_OF, AT_LEAST_ONE_OF].freeze
+
+        # For callers that need notes alone, which is every caller that has no
+        # nested scope to skip - see `#notes`.
+        def self.notes_for(route, attributes)
+          new(route, attributes).notes
+        end
+
+        # Appends a note to an existing description so the two read as separate
+        # sentences. Returns the note alone when there is no
+        # existing text.
+        def self.append_note(description, note)
+          text = description.to_s.strip
+          return note if text.empty?
+
+          text += '.' unless text.end_with?('.', '!', '?')
+          "#{text} #{note}"
+        end
+
+        # `attributes` are the param names the caller is able to annotate: a
+        # route's query params, or a request body's top-level properties. Both
+        # readers below share one walk of the route's validations, so a caller
+        # that needs both pays for it once.
+        def initialize(route, attributes)
+          @route = route
+          @attributes = attributes
+        end
+
+        # Per-param description notes for every cross-field constraint on the
+        # route, e.g. { 'files' => 'Mutually exclusive with `content`.' }.
+        # Notes from different constraints on the same param are
+        # joined. Returns {} when there are none.
+        def notes
+          @notes ||= matched_entries.each_with_object({}) do |(constraint, entries), result|
+            groups = annotatable_groups(entries)
+            next if groups.empty?
+
+            constraint[:notes].call(groups).each do |param, note|
+              result[param] = self.class.append_note(result[param], note)
+            end
+          end
+        end
+
+        # Constraints whose groups are too big to enumerate
+        # Adds configured custom summary or default summary for the entire group
+        # rather than one sentence per group member.
+        def oversized
+          @oversized ||= matched_entries.flat_map do |constraint, entries|
+            declared_groups(entries)
+              .select { |group| oversized?(group) }
+              .map { |group| { summary: format(constraint[:summary_format], group.length), size: group.length } }
+          end
+        end
+
+        # The groups `notes` could NOT annotate (a member isn't one of `attributes`).
+        def skipped
+          @skipped ||= matched_entries.flat_map do |_constraint, entries|
+            constrained_groups(entries).reject { |group| fully_known?(group) }
+          end.uniq
+        end
+
+        private
+
+        attr_reader :route, :attributes
+
+        def known_names
+          @known_names ||= Array(attributes).map(&:to_s)
+        end
+
+        # Groups all validations on the route
+        # Returns only validations with classes in CONSTRAINTS:
+        # [[MUTUALLY_EXCLUSIVE, [
+        #  { validator_class: Grape::Validations::Validators::MutualExclusionValidator,
+        #    full_names: ["content", "files"] }
+        #  ]]]
+        def matched_entries
+          @matched_entries ||= begin
+            by_validator = GrapeCompat.all_validations(route).group_by { |entry| validator_name(entry) }
+
+            CONSTRAINTS.map do |constraint|
+              [constraint, by_validator.values_at(*constraint[:classes]).compact.flatten]
+            end
+          end
+        end
+
+        # Groups whose members are all in the known set. The exact complement of
+        # what `skipped` keeps, so both derive from `fully_known?` rather than
+        # restating the condition and risking drift.
+        def annotatable_groups(entries)
+          constrained_groups(entries).select { |group| fully_known?(group) }
+        end
+
+        # Groups eligible for a per-param note: declared, and small enough that
+        # naming every member reads well.
+        def constrained_groups(entries)
+          declared_groups(entries).reject { |group| oversized?(group) }
+        end
+
+        # Every distinct group a constraint declares. A single-member group
+        # constrains nothing - Grape accepts `mutually_exclusive :a` - so it is
+        # neither annotated nor reported as skipped.
+        def declared_groups(entries)
+          entries.map { |entry| group_members(entry) }.uniq.select { |group| group.length >= 2 }
+        end
+
+        def oversized?(group)
+          group.length > config.cross_field_group_limit
+        end
+
+        def config
+          @config ||= Gitlab::GrapeOpenapi.configuration
+        end
+
+        # Whether the caller can annotate every member of the group.
+        def fully_known?(group)
+          (group - known_names).empty?
+        end
+
+        # eg. => 'Grape::Validations::Validators::MutuallyExclusiveValidator'
+        def validator_name(entry)
+          entry[:validator_class]&.name
+        end
+
+        # Full bracketed paths
+        # top level eg. ["author_id", "author_username"]
+        # nested(nested under `not:`) eg. ["not[author_id]", "not[author_username]"]
+        def group_members(entry)
+          Array(entry[:full_names]).map(&:to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,8 @@ module Gitlab
   module GrapeOpenapi
     module Converters
       class EntityConverter
+        include Concerns::Serializable
+
         attr_reader :entity_class, :schema_registry
 
         OBJECT_TYPE = 'object'
@@ -179,8 +181,8 @@ module Gitlab
 
           TypeResolver.union_schema(members).merge(
             description: documentation[:desc],
-            default: default_value,
-            example: documentation[:example]
+            default: stringify_symbols(default_value),
+            example: stringify_symbols(documentation[:example])
           )
         end
 
@@ -193,8 +195,8 @@ module Gitlab
             description: documentation[:desc],
             format: TypeResolver.resolve_format(documentation[:format], actual_type),
             enum: enum_values(documentation),
-            default: default_value,
-            example: documentation[:example]
+            default: stringify_symbols(default_value),
+            example: stringify_symbols(documentation[:example])
           }
         end
 
@@ -206,7 +208,7 @@ module Gitlab
           values = documentation[:values]
           return unless values.is_a?(Array) && values.any?
 
-          values.map { |value| value.is_a?(Symbol) ? value.to_s : value }
+          stringify_symbols(values)
         end
 
         def build_type_schema(type, documentation)

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

@@ -41,7 +41,7 @@ module Gitlab
           Models::Operation.new.tap do |operation|
             operation.operation_id = operation_id
             operation.summary = extract_description
-            operation.description = extract_detail
+            operation.description = annotate_oversized_constraints(extract_detail)
             operation.tags = extract_tags
             operation.deprecated = extract_deprecated
             operation.hidden = extract_hidden
@@ -77,10 +77,10 @@ module Gitlab
           params = if options[:params].empty?
                      []
                    else
-                     options[:params].filter_map do |key, options|
+                     options[:params].filter_map do |key, param_options|
                        Converters::ParameterConverter.convert(
                          key,
-                         options: options,
+                         options: annotate_constraint(key, param_options),
                          validations: validations_for(key.to_sym),
                          route: route
                        )
@@ -94,6 +94,68 @@ module Gitlab
           params.reject { |param| removed.include?(param.name.to_s) }
         end
 
+        def annotate_constraint(key, param_options)
+          note = cross_field_notes[key.to_s]
+          return param_options unless note
+
+          param_options.merge(desc: Converters::CrossFieldValidationResolver.append_note(param_options[:desc], note))
+        end
+
+        # Per-param cross-field constraint notes to fold into descriptions, e.g.
+        #   { 'author_id' => 'Mutually exclusive with `author_username`.' }.
+        # Keyed by the full bracketed param name, so a nested-Hash query filter
+        # (`not[author_id]`, which Grape flattens into `options[:params]`) is
+        # annotated the same way a top-level param is.
+        def cross_field_notes
+          cross_field_resolver.notes
+        end
+
+        # Built over every declared param, body ones included, so an oversized
+        # group is found even when its members document a request body.
+        def cross_field_resolver
+          @cross_field_resolver ||=
+            Converters::CrossFieldValidationResolver.new(route, options[:params].keys.map(&:to_s))
+        end
+
+        # A group too large to enumerate is stated once on the operation rather
+        # than on every member.
+        def annotate_oversized_constraints(description)
+          oversized = cross_field_resolver.oversized
+          return description if oversized.empty?
+
+          message = configured_message
+          report_oversized_constraints(oversized) unless message
+          sentences = message ? [message] : oversized.map { |group| group[:summary] }.uniq
+
+          sentences.reduce(description) do |text, sentence|
+            Converters::CrossFieldValidationResolver.append_note(text, sentence)
+          end
+        end
+
+        # A blank entry counts as absent. Left as-is it would satisfy the
+        # `unless message` guard, silencing the sentence and the warning together
+        # and leaving the constraint undocumented with nothing to show for it.
+        def configured_message
+          message = config.cross_field_messages[endpoint_key]
+          message unless message.to_s.strip.empty?
+        end
+
+        def report_oversized_constraints(oversized)
+          return unless config.warnings
+
+          oversized.each do |group|
+            warn "[gitlab-grape-openapi] oversized cross-field constraint: " \
+              "#{endpoint_key} params=#{group[:size]} " \
+              "(limit #{config.cross_field_group_limit}, using generic sentence)"
+          end
+        end
+
+        # Keyed on the route's own path rather than `normalized_path`. Matches the
+        # string the warnings print, so stderr says what to put in the config.
+        def endpoint_key
+          "#{http_method} #{normalize_path_pattern}"
+        end
+
         def inject_missing_path_parameters(params)
           declared_names = params.map(&:name).to_set
 
@@ -218,9 +280,7 @@ module Gitlab
         end
 
         def normalize_path_pattern
-          NormalizedPath.new(pattern.origin).to_s
-            .gsub(/[()\\]/, '')
-            .gsub('{version}', config.api_version)
+          NormalizedPath.new(pattern.origin).to_display_path(config.api_version)
         end
 
         def camelize(string)

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

@@ -9,6 +9,7 @@ module Gitlab
         include Concerns::LimitResolver
         include Concerns::FailFastAnnotatable
         include Concerns::RegexConverter
+        include Concerns::Nullability
 
         attr_reader :name, :options, :validations, :route
 
@@ -57,7 +58,7 @@ 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)
@@ -91,7 +92,7 @@ module Gitlab
 
         def build_enum_schema(object_type)
           schema = { type: object_type }
-          schema[:enum] = options[:values] unless options[:values].is_a?(Proc)
+          schema[:enum] = stringify_symbols(options[:values]) unless options[:values].is_a?(Proc)
           schema
         end
 
@@ -203,24 +204,6 @@ module Gitlab
 
           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 union_members
-              union_members.each { |s| s[:nullable] = true }
-            else
-              schema[:nullable] = true
-            end
-          end
-        end
       end
     end
   end

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

@@ -48,7 +48,8 @@ module Gitlab
             add_response_with_entity(
               status_code: success_code,
               description: http_status_text(success_code),
-              entity_class: entity_class
+              entity_class: entity_class,
+              is_array: declared_is_array?
             )
           else
             success_code = infer_success_code(with_body: declared_body?)
@@ -68,7 +69,8 @@ module Gitlab
               description: entity_hash[:message] || http_status_text(status_code),
               entity_class: entity_hash[:model],
               example: entity_hash[:example],
-              examples: entity_hash[:examples]
+              examples: entity_hash[:examples],
+              is_array: entity_hash.fetch(:is_array, declared_is_array?)
             )
           else
             status_code = entity_hash[:code] || infer_success_code(with_body: declared_body?)
@@ -99,7 +101,8 @@ module Gitlab
               description: definition[:message] || http_status_text(status_code),
               entity_class: definition[:model],
               example: definition[:example],
-              examples: definition[:examples]
+              examples: definition[:examples],
+              is_array: definition.fetch(:is_array, declared_is_array?)
             )
           else
             status_code = definition[:code] || infer_success_code(with_body: declared_body?)
@@ -132,13 +135,15 @@ module Gitlab
           end
         end
 
-        def add_response_with_entity(status_code:, description:, entity_class:, example: nil, examples: nil)
+        def add_response_with_entity(
+          status_code:, description:, entity_class:, example: nil, examples: nil, is_array: false)
           response = Models::Response.new(
             status_code: status_code,
             description: description,
             entity_class: entity_class,
             example: example,
-            examples: examples
+            examples: examples,
+            is_array: is_array
           )
 
           @responses[response.status_code] = response.to_h(@schema_registry)
@@ -188,6 +193,14 @@ module Gitlab
           content unless content.empty?
         end
 
+        # `is_array` can be declared standalone in the `desc` block (the common
+        # form) instead of inline in the `success`/`entity` hash, in which case
+        # it lands next to `produces` rather than in the success declaration.
+        # Inline keys take precedence over this fallback.
+        def declared_is_array?
+          !!@route.settings.dig(:description, :is_array)
+        end
+
         # An explicit `produces` overrides `success File`, matching grape-swagger existing behaviour.
         def declared_media_types
           produces = MediaTypeResolver.normalize(@route.settings.dig(:description, :produces))

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,6 +21,16 @@ 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
@@ -43,8 +49,21 @@ module Gitlab
 
         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.
@@ -57,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

data/lib/gitlab/grape_openapi/models/parameter.rb

@@ -4,6 +4,8 @@ module Gitlab
   module GrapeOpenapi
     module Models
       class Parameter
+        include Concerns::Serializable
+
         # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#parameter-object
         attr_reader :name, :required, :in_value, :description, :options, :schema, :example
         attr_accessor :style, :explode
@@ -17,7 +19,7 @@ module Gitlab
           @description = options[:desc]
           @schema = schema
           @in_value = in_value
-          @example = options.dig(:documentation, :example)
+          @example = stringify_symbols(options.dig(:documentation, :example))
           @default = options.dig(:documentation, :default)
           @style = nil
           @explode = nil

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

@@ -10,6 +10,7 @@ module Gitlab
           include Concerns::LimitResolver
           include Concerns::FailFastAnnotatable
           include Concerns::RegexConverter
+          include Concerns::Nullability
 
           def initialize(route:, key:, param_options:)
             @route = route
@@ -29,7 +30,7 @@ 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])
@@ -128,7 +129,7 @@ module Gitlab
 
           def build_enum_schema(object_type)
             schema = { type: object_type }
-            schema[:enum] = param_options[:values] unless param_options[:values].is_a?(Proc)
+            schema[:enum] = stringify_symbols(param_options[:values]) unless param_options[:values].is_a?(Proc)
             schema[:description] = annotated_description if param_options[:desc]
             schema
           end
@@ -202,7 +203,7 @@ module Gitlab
             schema[:description] = annotated_description if param_options[:desc]
 
             if param_options.dig(:documentation, :example)
-              schema[:example] = param_options.dig(:documentation, :example)
+              schema[:example] = stringify_symbols(param_options.dig(:documentation, :example))
             end
 
             # Add regex validations
@@ -221,18 +222,6 @@ module Gitlab
           def validations_for(attribute)
             GrapeCompat.validations_for(route, attribute)
           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 union_members
-              union_members.each { |s| s[:nullable] = true }
-            else
-              schema[:nullable] = true
-            end
-          end
         end
       end
     end

data/lib/gitlab/grape_openapi/models/response.rb

@@ -9,7 +9,7 @@ module Gitlab
 
         def initialize(
           status_code:, description:, entity_class:, headers: {}, content_type: 'application/json',
-          example: nil, examples: nil)
+          example: nil, examples: nil, is_array: false)
           @status_code = status_code.to_s
           @description = description
           @entity_class = entity_class
@@ -17,6 +17,7 @@ module Gitlab
           @content_type = content_type
           @example = example
           @examples = examples
+          @is_array = is_array
         end
 
         def to_h(schema_registry)
@@ -24,7 +25,7 @@ module Gitlab
             description: description,
             content: {
               content_type => {
-                schema: { '$ref' => schema_ref(schema_registry) },
+                schema: schema(schema_registry),
                 example: @example,
                 examples: @examples
               }.compact
@@ -38,6 +39,15 @@ module Gitlab
 
         private
 
+        # `is_array: true` on a `success`/`entity` declaration means the route
+        # renders a collection of the entity, not a single instance.
+        def schema(schema_registry)
+          reference = { '$ref' => schema_ref(schema_registry) }
+          return reference unless @is_array
+
+          { type: 'array', items: reference }
+        end
+
         def schema_ref(schema_registry)
           normalized_name = schema_registry.register(entity_class, nil)
           "#/components/schemas/#{normalized_name}"

data/lib/gitlab/grape_openapi/normalized_path.rb

@@ -21,6 +21,11 @@ module Gitlab
       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'
@@ -40,6 +45,13 @@ module Gitlab
           .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 `/`,

data/lib/gitlab/grape_openapi/version.rb

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

data/lib/gitlab-grape-openapi.rb

@@ -15,12 +15,14 @@ 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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-grape-openapi
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - group::api
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -142,10 +142,12 @@ files:
 - 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