gitlab-grape-openapi 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c0d95f2bff47a6ef1c1c9d251b48b4e12748f8348b112a408cf94c97d62b6d3
-  data.tar.gz: 166affd62ad738cdd13b2c414bb131fd9065506c18b3dee7e32dc861ad23e3fd
+  metadata.gz: 10a34008541dedbab4063d199bbdb94f2d669d94101be45af1023e362bf8c72f
+  data.tar.gz: ba640eb0b0553149b7776bd53afef9eee0c2cc5316dbb4917c44c2099b138d0e
 SHA512:
-  metadata.gz: a8695acf55cddb13dc6ad5078a2ea7fca4e251abe152f9c45b9457018bc47eda0708ff7a9e018713cf6ba6ac77532d65368a31112cc4cb1d4b61a9be9d1c9f80
-  data.tar.gz: 7de023af2bf2810e32513a09b2ea6c2520ea1b1d4a46be61f5ff6acf84637dfe6d1ab922bb51a0b223186f0baa3530ad9b19b229eca8c535e63f3e25c1936ee0
+  metadata.gz: fd55dfbd2de53ec38abfd182f89d2dcbf2f03b916fbde38525dd8566c5984d134b21a9ff112123a7d2d9dbec0fc8077c8bf4a04d40117c902215e4a4cb6eb52b
+  data.tar.gz: 4ece03be3b48a4f4082539446d72ab4ac68b8cd0a022ee125f777c7196dd2aac73b154bc98f1518ac078da6b13b26a80c0a0a4dfabada8f220d461b507202e2c

data/README.md

@@ -88,6 +88,14 @@ 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
 ```
 
@@ -104,6 +112,8 @@ end
 | `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
 
@@ -192,15 +202,37 @@ Generator
 
 ### Parameter constraints
 
-The gem documents Grape's `mutually_exclusive` param constraint by appending a
-note such as ``Mutually exclusive with `author_username`.`` 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`).
+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). A param appearing in several
-declarations lists every partner in its note.
+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
@@ -209,8 +241,8 @@ 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 sibling constraints (`exactly_one_of`,
-`at_least_one_of`, `all_or_none_of`) are not yet supported.
+is visible in source. The remaining sibling constraint (`all_or_none_of`) is not
+yet supported.
 
 ### Registries
 
@@ -221,8 +253,23 @@ is visible in source. The sibling constraints (`exactly_one_of`,
 ### 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/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

@@ -8,7 +8,7 @@
 # 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 several)
+# 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 }`.
@@ -20,11 +20,22 @@ 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] = [] }
 
@@ -42,7 +53,23 @@ module Gitlab
           end
         }.freeze
 
-        CONSTRAINTS = [MUTUALLY_EXCLUSIVE].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`.
@@ -85,6 +112,17 @@ module Gitlab
           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|
@@ -123,13 +161,27 @@ module Gitlab
           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 constrained_groups(entries)
+        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?

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
@@ -107,8 +107,53 @@ module Gitlab
         # (`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_notes ||=
-            Converters::CrossFieldValidationResolver.notes_for(route, options[:params].keys.map(&:to_s))
+          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)

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

@@ -92,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
 

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/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

@@ -129,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
@@ -203,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

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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-grape-openapi
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - group::api
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-03 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape