gitlab-grape-openapi 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3c0d95f2bff47a6ef1c1c9d251b48b4e12748f8348b112a408cf94c97d62b6d3
4
- data.tar.gz: 166affd62ad738cdd13b2c414bb131fd9065506c18b3dee7e32dc861ad23e3fd
3
+ metadata.gz: b864030f21b5380efa37ccb02b953f5c8d07b2f4d2fe90eb66334e155674e2bc
4
+ data.tar.gz: 37b0f04c277c0b1f1027bdb5f0839f06641a3c6e11fd2e9498cb9a192899914b
5
5
  SHA512:
6
- metadata.gz: a8695acf55cddb13dc6ad5078a2ea7fca4e251abe152f9c45b9457018bc47eda0708ff7a9e018713cf6ba6ac77532d65368a31112cc4cb1d4b61a9be9d1c9f80
7
- data.tar.gz: 7de023af2bf2810e32513a09b2ea6c2520ea1b1d4a46be61f5ff6acf84637dfe6d1ab922bb51a0b223186f0baa3530ad9b19b229eca8c535e63f3e25c1936ee0
6
+ metadata.gz: d7e270e89449c2f1dbdfa2f6acb4bb841abf7bbb25adf064a3f41fbf2a61eb8e9f86f698d8c826cdb111cf19aa6f21269984453913fc53554ce6f7f8eb502ba8
7
+ data.tar.gz: a6e772a0f79d6d1e010ddddf7a6504a96da9d94c2ad34db08bbf58d80e7bffd8df0364dc09b361c0da5cce3d2b163a2dc24cb5d57604a543926a2c1ddc4ed5fa
data/README.md CHANGED
@@ -17,6 +17,28 @@
17
17
 
18
18
  Internal gem for generating [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.0) specifications from [Grape](https://github.com/ruby-grape/grape) API definitions, used by [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) to publish its REST API reference.
19
19
 
20
+ ## Table of contents
21
+
22
+ - [Installation](#installation)
23
+ - [Configuration](#configuration)
24
+ - [Configuration Options](#configuration-options)
25
+ - [Annotations](#annotations)
26
+ - [Usage](#usage)
27
+ - [Generating an OpenAPI Specification](#generating-an-openapi-specification)
28
+ - [Usage with `gitlab-org/gitlab`](#usage-with-gitlab-orggitlab)
29
+ - [Architecture](#architecture)
30
+ - [Parameter constraints](#parameter-constraints)
31
+ - [Registries](#registries)
32
+ - [Response media types](#response-media-types)
33
+ - [Optional path segments](#optional-path-segments)
34
+ - [Operation IDs and request body schemas](#operation-ids-and-request-body-schemas)
35
+ - [Development](#development)
36
+ - [Running Tests](#running-tests)
37
+ - [Linting](#linting)
38
+ - [Releasing](#releasing)
39
+ - [Contributing](#contributing)
40
+ - [License](#license)
41
+
20
42
  ## Installation
21
43
 
22
44
  Add to your Gemfile:
@@ -44,6 +66,8 @@ Gitlab::GrapeOpenapi.configure do |config|
44
66
  version: 'v1',
45
67
  terms_of_service: 'https://example.com/terms'
46
68
  )
69
+ # A plain Hash (symbol or string keys) is also accepted and wrapped in Models::Info:
70
+ # config.info = { title: 'My API', version: 'v1' }
47
71
 
48
72
  # API path configuration
49
73
  config.api_prefix = "api" # Default: "api"
@@ -88,6 +112,14 @@ Gitlab::GrapeOpenapi.configure do |config|
88
112
  config.annotations = {
89
113
  lifecycle: 'x-gitlab-lifecycle'
90
114
  }
115
+
116
+ # Cross-field groups larger than this are stated once on the endpoint
117
+ config.cross_field_group_limit = 30
118
+
119
+ # Endpoint wording for those, keyed by "METHOD /path"
120
+ config.cross_field_messages = {
121
+ 'PUT /api/v4/application/settings' => 'At least one setting must be updated.'
122
+ }
91
123
  end
92
124
  ```
93
125
 
@@ -95,7 +127,7 @@ end
95
127
 
96
128
  | Option | Type | Default | Description |
97
129
  | ---------------------- | ------------------------------- | ------- | ---------------------------------------------------------------- |
98
- | `info` | `Models::Info` | `nil` | API metadata (title, description, version, terms of service) |
130
+ | `info` | `Models::Info` or `Hash` | `nil` | **Required.** API metadata (title, description, version, terms of service). `title` and `version` must be present and non-blank (not empty or whitespace-only), otherwise generation raises `Gitlab::GrapeOpenapi::ConfigurationError`. A `Hash` is wrapped in `Models::Info`; any other type also raises `ConfigurationError`. |
99
131
  | `api_prefix` | `String` | `"api"` | URL prefix for API routes |
100
132
  | `api_version` | `String` | `"v1"` | API version string |
101
133
  | `servers` | `Array<Models::Server>` | `[]` | Server definitions for the API |
@@ -104,6 +136,8 @@ end
104
136
  | `tag_overrides` | `Hash` | `{}` | Map of tag names to their display overrides |
105
137
  | `annotations` | `Hash` | `{}` | Map of Grape route settings to OpenAPI extension names |
106
138
  | `warnings` | `Boolean` | `false` | Emit stderr warnings for synthesized params, skipped constraints |
139
+ | `cross_field_group_limit` | `Integer` | `30` | Cross-field groups larger than this are summarised on the endpoint |
140
+ | `cross_field_messages` | `Hash` | `{}` | Endpoint wording for summarised groups, keyed by `"METHOD /path"` |
107
141
 
108
142
  ### Annotations
109
143
 
@@ -113,6 +147,7 @@ The `annotations` configuration maps Grape route settings to OpenAPI vendor exte
113
147
  config.annotations = {
114
148
  lifecycle: 'x-gitlab-lifecycle'
115
149
  }
150
+ ```
116
151
 
117
152
  When a Grape endpoint has:
118
153
 
@@ -192,15 +227,39 @@ Generator
192
227
 
193
228
  ### Parameter constraints
194
229
 
195
- The gem documents Grape's `mutually_exclusive` param constraint by appending a
196
- note such as ``Mutually exclusive with `author_username`.`` to each affected
197
- parameter's (or request-body property's) `description` — for both query/path
198
- params (`GET`/`DELETE`) and request-body params (`POST`/`PUT`/`PATCH`).
230
+ The gem documents Grape's cross-field param constraints by appending a note to
231
+ each affected parameter's (or request-body property's) `description` — for both
232
+ query/path params (`GET`/`DELETE`) and request-body params
233
+ (`POST`/`PUT`/`PATCH`). All four of Grape's cross-field constraints are
234
+ supported:
235
+
236
+ | Grape declaration | Note appended to every member |
237
+ |-------------------|-------------------------------|
238
+ | `mutually_exclusive :author_id, :author_username` | ``Mutually exclusive with `author_username`.`` |
239
+ | `exactly_one_of :project_id, :project_path` | ``Exactly one of `project_id`, `project_path` must be provided.`` |
240
+ | `at_least_one_of :assignee_id, :reviewer_id` | ``At least one of `assignee_id`, `reviewer_id` must be provided.`` |
241
+ | `all_or_none_of :extern_uid, :provider` | ``All or none of `extern_uid`, `provider` must be provided.`` |
199
242
 
200
243
  OpenAPI 3.0 has no cross-parameter constraint keyword, and the target renderer
201
244
  (Scalar) does not render JSON Schema `not`/`allOf`, so the constraint is stated
202
- in prose; Grape enforces it at runtime (HTTP 400). A param appearing in several
203
- declarations lists every partner in its note.
245
+ in prose; Grape enforces it at runtime (HTTP 400). Members of these groups stay
246
+ individually optional — the constraint binds the group, not any single param, so
247
+ no `required` entry is emitted.
248
+
249
+ They differ in how several declarations over one param are combined. Only
250
+ `mutually_exclusive` is pairwise, so a param lists every partner in one note. The
251
+ group constraints do not compose that way, so each declaration is stated as its
252
+ own sentence: `at_least_one_of :a, :b` alongside `at_least_one_of :a, :c` forbids
253
+ `b` alone, which the collapsed "At least one of `a`, `b`, `c`" would allow.
254
+
255
+ A group large enough that naming every member becomes unreadable — GitLab's
256
+ `PUT /api/v4/application/settings` declares `at_least_one_of` over 664 params — is
257
+ not enumerated. The rule is stated once on the endpoint's own `description`
258
+ instead, and its members keep their original descriptions. `cross_field_group_limit`
259
+ sets the threshold; `cross_field_messages` supplies wording per endpoint, keyed by
260
+ the same `"METHOD /path"` string the warnings print. Without an entry the gem uses
261
+ a generic sentence and, with `warnings` enabled, names the endpoint so wording can
262
+ be added.
204
263
 
205
264
  The gem reads the validation stack through `grape_compat`, so this works on both
206
265
  Grape 2.4 and 3.2. Each group is keyed by the full bracketed param path
@@ -209,8 +268,7 @@ param into the route's query params, a constraint nested inside a `Hash` *query*
209
268
  filter is documented the same as a top-level one. A constraint nested inside a
210
269
  request-body object property has no top-level property to attach to and is
211
270
  skipped; when `warnings` is enabled the gem logs one line per skipped group so it
212
- is visible in source. The sibling constraints (`exactly_one_of`,
213
- `at_least_one_of`, `all_or_none_of`) are not yet supported.
271
+ is visible in source.
214
272
 
215
273
  ### Registries
216
274
 
@@ -221,8 +279,23 @@ is visible in source. The sibling constraints (`exactly_one_of`,
221
279
  ### Response media types
222
280
 
223
281
  Responses default to `application/json`, described by the `$ref` of the entity
224
- declared with `success` / `entity`. Endpoints that return a file or plain text
225
- instead declare their media type with `produces` in the `desc` block:
282
+ declared with `success` / `entity`. Declaring the route as a collection wraps
283
+ that `$ref` in a `type: array` / `items:` schema, so a collection endpoint is
284
+ not published as a single object. Both of Grape's forms are honoured — inline
285
+ in the declaration (`success code: 200, model: Entities::Tag, is_array: true`)
286
+ and standalone in the `desc` block:
287
+
288
+ ```ruby
289
+ desc 'List tags' do
290
+ success code: 200, model: Entities::Tag
291
+ is_array true
292
+ end
293
+ ```
294
+
295
+ An inline `is_array:` takes precedence over the standalone setting.
296
+
297
+ Endpoints that return a file or plain text instead declare their media type
298
+ with `produces` in the `desc` block:
226
299
 
227
300
  ```ruby
228
301
  desc 'Download an export' do
@@ -289,6 +362,17 @@ Generating the combinatorial set of paths for routes with more than one
289
362
  param-bearing optional segment is **not** supported: such a route raises
290
363
  `Gitlab::GrapeOpenapi::MultipleOptionalSegmentsError`.
291
364
 
365
+ ### Operation IDs and request body schemas
366
+
367
+ Operation IDs are derived from the HTTP method and normalized route path. If
368
+ two routes produce the same ID, the later operation receives a numeric suffix
369
+ such as `_2`, keeping IDs unique without renaming unaffected operations.
370
+
371
+ Inline request bodies are emitted as component schemas named
372
+ `<operationId>Request`. The name is independent of the body shape, so adding or
373
+ changing a field does not rename the generated schema; identical bodies on
374
+ different operations retain their own operation-specific names.
375
+
292
376
  ## Development
293
377
 
294
378
  ```bash
@@ -16,7 +16,7 @@ module Gitlab
16
16
  return unless schema[:type] == 'array' && schema[:items].is_a?(Hash)
17
17
  return unless values.is_a?(Array)
18
18
 
19
- schema[:items][:enum] = values
19
+ schema[:items][:enum] = stringify_symbols(values)
20
20
  end
21
21
 
22
22
  def apply_default!(schema, default, example: nil)
@@ -33,7 +33,7 @@ module Gitlab
33
33
  def resolve_default(default, example: nil) # rubocop:disable Lint/UnusedMethodArgument -- overridden
34
34
  return unless serializable?(default)
35
35
 
36
- default
36
+ stringify_symbols(default)
37
37
  end
38
38
 
39
39
  # When a union (oneOf) schema has a `default:`, attach it to every member
@@ -45,7 +45,7 @@ module Gitlab
45
45
  return unless serializable?(default)
46
46
 
47
47
  members.each do |member|
48
- member[:default] = default if member_accepts_default?(member, default)
48
+ member[:default] = stringify_symbols(default) if member_accepts_default?(member, default)
49
49
  end
50
50
  end
51
51
 
@@ -13,6 +13,16 @@ module Gitlab
13
13
 
14
14
  true
15
15
  end
16
+
17
+ # Symbol maps to OpenAPI `string`, so Symbol values must become strings too.
18
+ # Otherwise a Symbol serializes as `:value` in YAML, which parsers read back as that string.
19
+ def stringify_symbols(value)
20
+ case value
21
+ when Symbol then value.to_s
22
+ when Array then value.map { |element| stringify_symbols(element) }
23
+ else value
24
+ end
25
+ end
16
26
  end
17
27
  end
18
28
  end
@@ -4,7 +4,8 @@ module Gitlab
4
4
  module GrapeOpenapi
5
5
  class Configuration
6
6
  attr_accessor :api_version, :api_prefix, :excluded_api_classes, :servers, :security_schemes, :info,
7
- :tag_overrides, :annotations, :coercer_mappings, :warnings
7
+ :tag_overrides, :annotations, :coercer_mappings, :warnings,
8
+ :cross_field_group_limit, :cross_field_messages
8
9
 
9
10
  def initialize
10
11
  @api_prefix = "api"
@@ -19,6 +20,12 @@ module Gitlab
19
20
  @annotations = {}
20
21
  @coercer_mappings = {}
21
22
  @warnings = false
23
+
24
+ # Cross field validations
25
+ # Allow custom descriptions for endpoints whose groups of cross-validated
26
+ # params exceed cross_field_group_limit
27
+ @cross_field_group_limit = 30
28
+ @cross_field_messages = {}
22
29
  end
23
30
  end
24
31
  end
@@ -8,7 +8,7 @@
8
8
  # Grape enforces them at runtime (HTTP 400).
9
9
  #
10
10
  # Each cross-field validator is a CONSTRAINTS entry pairing the validator class
11
- # names it carries across supported Grape versions (Grape 3.2 renamed several)
11
+ # names it carries across supported Grape versions (Grape 3.2 renamed one)
12
12
  # with a note strategy. A strategy receives every group of its kind found on the
13
13
  # route (each group an array of top-level attribute-name strings) and returns
14
14
  # `{ param => note }`.
@@ -20,11 +20,22 @@ module Gitlab
20
20
  module GrapeOpenapi
21
21
  module Converters
22
22
  class CrossFieldValidationResolver
23
+ GROUP_SENTENCE = lambda do |lead|
24
+ lambda do |groups|
25
+ groups.each_with_object({}) do |group, result|
26
+ note = "#{lead} #{group.map { |name| "`#{name}`" }.join(', ')} must be provided."
27
+
28
+ group.each { |name| result[name] = append_note(result[name], note) }
29
+ end
30
+ end
31
+ end
32
+
23
33
  MUTUALLY_EXCLUSIVE = {
24
34
  classes: [
25
35
  'Grape::Validations::Validators::MutualExclusionValidator', # Grape < 3.2
26
36
  'Grape::Validations::Validators::MutuallyExclusiveValidator' # Grape >= 3.2
27
37
  ].freeze,
38
+ summary_format: 'At most one of %d related parameters may be provided.',
28
39
  notes: lambda do |groups|
29
40
  partners = Hash.new { |hash, key| hash[key] = [] }
30
41
 
@@ -42,7 +53,31 @@ module Gitlab
42
53
  end
43
54
  }.freeze
44
55
 
45
- CONSTRAINTS = [MUTUALLY_EXCLUSIVE].freeze
56
+ EXACTLY_ONE_OF = {
57
+ classes: [
58
+ 'Grape::Validations::Validators::ExactlyOneOfValidator' # Grape all versions
59
+ ].freeze,
60
+ summary_format: 'Exactly one of %d related parameters must be provided.',
61
+ notes: GROUP_SENTENCE.call('Exactly one of')
62
+ }.freeze
63
+
64
+ AT_LEAST_ONE_OF = {
65
+ classes: [
66
+ 'Grape::Validations::Validators::AtLeastOneOfValidator' # Grape all versions
67
+ ].freeze,
68
+ summary_format: 'At least one of %d related parameters must be provided.',
69
+ notes: GROUP_SENTENCE.call('At least one of')
70
+ }.freeze
71
+
72
+ ALL_OR_NONE_OF = {
73
+ classes: [
74
+ 'Grape::Validations::Validators::AllOrNoneOfValidator' # Grape all versions
75
+ ].freeze,
76
+ summary_format: '%d related parameters must be provided together, or not at all.',
77
+ notes: GROUP_SENTENCE.call('All or none of')
78
+ }.freeze
79
+
80
+ CONSTRAINTS = [MUTUALLY_EXCLUSIVE, EXACTLY_ONE_OF, AT_LEAST_ONE_OF, ALL_OR_NONE_OF].freeze
46
81
 
47
82
  # For callers that need notes alone, which is every caller that has no
48
83
  # nested scope to skip - see `#notes`.
@@ -85,6 +120,17 @@ module Gitlab
85
120
  end
86
121
  end
87
122
 
123
+ # Constraints whose groups are too big to enumerate
124
+ # Adds configured custom summary or default summary for the entire group
125
+ # rather than one sentence per group member.
126
+ def oversized
127
+ @oversized ||= matched_entries.flat_map do |constraint, entries|
128
+ declared_groups(entries)
129
+ .select { |group| oversized?(group) }
130
+ .map { |group| { summary: format(constraint[:summary_format], group.length), size: group.length } }
131
+ end
132
+ end
133
+
88
134
  # The groups `notes` could NOT annotate (a member isn't one of `attributes`).
89
135
  def skipped
90
136
  @skipped ||= matched_entries.flat_map do |_constraint, entries|
@@ -123,13 +169,27 @@ module Gitlab
123
169
  constrained_groups(entries).select { |group| fully_known?(group) }
124
170
  end
125
171
 
172
+ # Groups eligible for a per-param note: declared, and small enough that
173
+ # naming every member reads well.
174
+ def constrained_groups(entries)
175
+ declared_groups(entries).reject { |group| oversized?(group) }
176
+ end
177
+
126
178
  # Every distinct group a constraint declares. A single-member group
127
179
  # constrains nothing - Grape accepts `mutually_exclusive :a` - so it is
128
180
  # neither annotated nor reported as skipped.
129
- def constrained_groups(entries)
181
+ def declared_groups(entries)
130
182
  entries.map { |entry| group_members(entry) }.uniq.select { |group| group.length >= 2 }
131
183
  end
132
184
 
185
+ def oversized?(group)
186
+ group.length > config.cross_field_group_limit
187
+ end
188
+
189
+ def config
190
+ @config ||= Gitlab::GrapeOpenapi.configuration
191
+ end
192
+
133
193
  # Whether the caller can annotate every member of the group.
134
194
  def fully_known?(group)
135
195
  (group - known_names).empty?
@@ -4,6 +4,8 @@ module Gitlab
4
4
  module GrapeOpenapi
5
5
  module Converters
6
6
  class EntityConverter
7
+ include Concerns::Serializable
8
+
7
9
  attr_reader :entity_class, :schema_registry
8
10
 
9
11
  OBJECT_TYPE = 'object'
@@ -179,8 +181,8 @@ module Gitlab
179
181
 
180
182
  TypeResolver.union_schema(members).merge(
181
183
  description: documentation[:desc],
182
- default: default_value,
183
- example: documentation[:example]
184
+ default: stringify_symbols(default_value),
185
+ example: stringify_symbols(documentation[:example])
184
186
  )
185
187
  end
186
188
 
@@ -193,8 +195,8 @@ module Gitlab
193
195
  description: documentation[:desc],
194
196
  format: TypeResolver.resolve_format(documentation[:format], actual_type),
195
197
  enum: enum_values(documentation),
196
- default: default_value,
197
- example: documentation[:example]
198
+ default: stringify_symbols(default_value),
199
+ example: stringify_symbols(documentation[:example])
198
200
  }
199
201
  end
200
202
 
@@ -206,7 +208,7 @@ module Gitlab
206
208
  values = documentation[:values]
207
209
  return unless values.is_a?(Array) && values.any?
208
210
 
209
- values.map { |value| value.is_a?(Symbol) ? value.to_s : value }
211
+ stringify_symbols(values)
210
212
  end
211
213
 
212
214
  def build_type_schema(type, documentation)
@@ -10,23 +10,25 @@ module Gitlab
10
10
 
11
11
  def self.convert(
12
12
  route, schema_registry, request_body_registry, inherited_path_params: {},
13
- path_override: nil, removed_params: [])
13
+ path_override: nil, removed_params: [], operation_id_registry: nil)
14
14
  new(
15
15
  route,
16
16
  schema_registry,
17
17
  request_body_registry,
18
18
  inherited_path_params: inherited_path_params,
19
19
  path_override: path_override,
20
- removed_params: removed_params
20
+ removed_params: removed_params,
21
+ operation_id_registry: operation_id_registry
21
22
  ).convert
22
23
  end
23
24
 
24
25
  def initialize(
25
26
  route, schema_registry, request_body_registry, inherited_path_params: {},
26
- path_override: nil, removed_params: [])
27
+ path_override: nil, removed_params: [], operation_id_registry: nil)
27
28
  @route = route
28
29
  @schema_registry = schema_registry
29
30
  @request_body_registry = request_body_registry
31
+ @operation_id_registry = operation_id_registry
30
32
  @inherited_path_params = inherited_path_params
31
33
  # @path_override and @removed_params are set together when optional-path-segment variants exist
32
34
  @path_override = path_override
@@ -38,16 +40,18 @@ module Gitlab
38
40
  end
39
41
 
40
42
  def convert
43
+ id = operation_id_registry ? operation_id_registry.register(operation_id) : operation_id
44
+
41
45
  Models::Operation.new.tap do |operation|
42
- operation.operation_id = operation_id
46
+ operation.operation_id = id
43
47
  operation.summary = extract_description
44
- operation.description = extract_detail
48
+ operation.description = annotate_oversized_constraints(extract_detail)
45
49
  operation.tags = extract_tags
46
50
  operation.deprecated = extract_deprecated
47
51
  operation.hidden = extract_hidden
48
52
  operation.parameters = extract_parameters
49
53
  operation.responses = ResponseConverter.new(@route, @schema_registry).convert
50
- operation.request_body = extract_request_body || {}
54
+ operation.request_body = extract_request_body(id) || {}
51
55
  operation.annotations = extract_annotations
52
56
  end
53
57
  end
@@ -55,7 +59,7 @@ module Gitlab
55
59
  private
56
60
 
57
61
  attr_reader :config, :route, :options, :pattern, :endpoint, :schema_registry, :request_body_registry,
58
- :inherited_path_params, :path_override, :removed_params
62
+ :inherited_path_params, :path_override, :removed_params, :operation_id_registry
59
63
 
60
64
  def route_method
61
65
  @route.request_method
@@ -107,8 +111,53 @@ module Gitlab
107
111
  # (`not[author_id]`, which Grape flattens into `options[:params]`) is
108
112
  # annotated the same way a top-level param is.
109
113
  def cross_field_notes
110
- @cross_field_notes ||=
111
- Converters::CrossFieldValidationResolver.notes_for(route, options[:params].keys.map(&:to_s))
114
+ cross_field_resolver.notes
115
+ end
116
+
117
+ # Built over every declared param, body ones included, so an oversized
118
+ # group is found even when its members document a request body.
119
+ def cross_field_resolver
120
+ @cross_field_resolver ||=
121
+ Converters::CrossFieldValidationResolver.new(route, options[:params].keys.map(&:to_s))
122
+ end
123
+
124
+ # A group too large to enumerate is stated once on the operation rather
125
+ # than on every member.
126
+ def annotate_oversized_constraints(description)
127
+ oversized = cross_field_resolver.oversized
128
+ return description if oversized.empty?
129
+
130
+ message = configured_message
131
+ report_oversized_constraints(oversized) unless message
132
+ sentences = message ? [message] : oversized.map { |group| group[:summary] }.uniq
133
+
134
+ sentences.reduce(description) do |text, sentence|
135
+ Converters::CrossFieldValidationResolver.append_note(text, sentence)
136
+ end
137
+ end
138
+
139
+ # A blank entry counts as absent. Left as-is it would satisfy the
140
+ # `unless message` guard, silencing the sentence and the warning together
141
+ # and leaving the constraint undocumented with nothing to show for it.
142
+ def configured_message
143
+ message = config.cross_field_messages[endpoint_key]
144
+ message unless message.to_s.strip.empty?
145
+ end
146
+
147
+ def report_oversized_constraints(oversized)
148
+ return unless config.warnings
149
+
150
+ oversized.each do |group|
151
+ warn "[gitlab-grape-openapi] oversized cross-field constraint: " \
152
+ "#{endpoint_key} params=#{group[:size]} " \
153
+ "(limit #{config.cross_field_group_limit}, using generic sentence)"
154
+ end
155
+ end
156
+
157
+ # Keyed on the route's own path rather than `normalized_path`. Matches the
158
+ # string the warnings print, so stderr says what to put in the config.
159
+ def endpoint_key
160
+ "#{http_method} #{normalize_path_pattern}"
112
161
  end
113
162
 
114
163
  def inject_missing_path_parameters(params)
@@ -256,12 +305,13 @@ module Gitlab
256
305
  GrapeCompat.validations_for(route, attribute)
257
306
  end
258
307
 
259
- def extract_request_body
308
+ def extract_request_body(id)
260
309
  RequestBodyConverter.convert(
261
310
  route: route,
262
311
  options: options,
263
312
  params: options[:params],
264
- request_body_registry: request_body_registry
313
+ request_body_registry: request_body_registry,
314
+ operation_id: id
265
315
  )
266
316
  end
267
317
  end
@@ -92,7 +92,7 @@ module Gitlab
92
92
 
93
93
  def build_enum_schema(object_type)
94
94
  schema = { type: object_type }
95
- schema[:enum] = options[:values] unless options[:values].is_a?(Proc)
95
+ schema[:enum] = stringify_symbols(options[:values]) unless options[:values].is_a?(Proc)
96
96
  schema
97
97
  end
98
98
 
@@ -31,6 +31,7 @@ module Gitlab
31
31
  @routes = routes
32
32
  @schema_registry = schema_registry
33
33
  @request_body_registry = request_body_registry
34
+ @operation_id_registry = OperationIdRegistry.new
34
35
  @config = Gitlab::GrapeOpenapi.configuration
35
36
  @inherited_path_params = {}
36
37
  end
@@ -116,15 +117,18 @@ module Gitlab
116
117
 
117
118
  def build_path_item(routes_for_path, variant)
118
119
  path_item = Models::PathItem.new
120
+ routes_by_method = routes_for_path.group_by { |route| extract_method(route) }
121
+ .transform_values(&:last)
119
122
 
120
- routes_for_path.each do |route|
123
+ routes_by_method.each_value do |route|
121
124
  operation = OperationConverter.convert(
122
125
  route,
123
126
  schema_registry,
124
127
  request_body_registry,
125
128
  inherited_path_params: inherited_path_params,
126
129
  path_override: variant.path_override,
127
- removed_params: variant.removed_params
130
+ removed_params: variant.removed_params,
131
+ operation_id_registry: @operation_id_registry
128
132
  )
129
133
  method = extract_method(route)
130
134
  path_item.add_operation(method, operation)
@@ -9,17 +9,19 @@ module Gitlab
9
9
  GET_METHOD = 'GET'
10
10
  DELETE_METHOD = 'DELETE'
11
11
 
12
- attr_reader :route, :options, :params, :request_body_registry
12
+ attr_reader :route, :options, :params, :request_body_registry, :operation_id
13
13
 
14
- def self.convert(route:, options:, params:, request_body_registry:)
15
- new(route: route, options: options, params: params, request_body_registry: request_body_registry).convert
14
+ def self.convert(route:, options:, params:, request_body_registry:, operation_id:)
15
+ new(route: route, options: options, params: params, request_body_registry: request_body_registry,
16
+ operation_id: operation_id).convert
16
17
  end
17
18
 
18
- def initialize(route:, options:, params:, request_body_registry:)
19
+ def initialize(route:, options:, params:, request_body_registry:, operation_id:)
19
20
  @route = route
20
21
  @options = options
21
22
  @params = params
22
23
  @request_body_registry = request_body_registry
24
+ @operation_id = operation_id
23
25
  end
24
26
 
25
27
  def convert
@@ -58,7 +60,7 @@ module Gitlab
58
60
  }
59
61
  schema[:required] = required_params unless required_params.empty?
60
62
 
61
- schema_ref = request_body_registry.register(schema)
63
+ schema_ref = request_body_registry.register(schema, name: "#{operation_id}Request")
62
64
 
63
65
  {
64
66
  required: required_params.any?,
@@ -48,7 +48,8 @@ module Gitlab
48
48
  add_response_with_entity(
49
49
  status_code: success_code,
50
50
  description: http_status_text(success_code),
51
- entity_class: entity_class
51
+ entity_class: entity_class,
52
+ is_array: declared_is_array?
52
53
  )
53
54
  else
54
55
  success_code = infer_success_code(with_body: declared_body?)
@@ -68,7 +69,8 @@ module Gitlab
68
69
  description: entity_hash[:message] || http_status_text(status_code),
69
70
  entity_class: entity_hash[:model],
70
71
  example: entity_hash[:example],
71
- examples: entity_hash[:examples]
72
+ examples: entity_hash[:examples],
73
+ is_array: entity_hash.fetch(:is_array, declared_is_array?)
72
74
  )
73
75
  else
74
76
  status_code = entity_hash[:code] || infer_success_code(with_body: declared_body?)
@@ -99,7 +101,8 @@ module Gitlab
99
101
  description: definition[:message] || http_status_text(status_code),
100
102
  entity_class: definition[:model],
101
103
  example: definition[:example],
102
- examples: definition[:examples]
104
+ examples: definition[:examples],
105
+ is_array: definition.fetch(:is_array, declared_is_array?)
103
106
  )
104
107
  else
105
108
  status_code = definition[:code] || infer_success_code(with_body: declared_body?)
@@ -132,13 +135,15 @@ module Gitlab
132
135
  end
133
136
  end
134
137
 
135
- def add_response_with_entity(status_code:, description:, entity_class:, example: nil, examples: nil)
138
+ def add_response_with_entity(
139
+ status_code:, description:, entity_class:, example: nil, examples: nil, is_array: false)
136
140
  response = Models::Response.new(
137
141
  status_code: status_code,
138
142
  description: description,
139
143
  entity_class: entity_class,
140
144
  example: example,
141
- examples: examples
145
+ examples: examples,
146
+ is_array: is_array
142
147
  )
143
148
 
144
149
  @responses[response.status_code] = response.to_h(@schema_registry)
@@ -188,6 +193,14 @@ module Gitlab
188
193
  content unless content.empty?
189
194
  end
190
195
 
196
+ # `is_array` can be declared standalone in the `desc` block (the common
197
+ # form) instead of inline in the `success`/`entity` hash, in which case
198
+ # it lands next to `produces` rather than in the success declaration.
199
+ # Inline keys take precedence over this fallback.
200
+ def declared_is_array?
201
+ !!@route.settings.dig(:description, :is_array)
202
+ end
203
+
191
204
  # An explicit `produces` overrides `success File`, matching grape-swagger existing behaviour.
192
205
  def declared_media_types
193
206
  produces = MediaTypeResolver.normalize(@route.settings.dig(:description, :produces))
@@ -15,11 +15,13 @@ module Gitlab
15
15
  end
16
16
 
17
17
  def generate
18
+ # Resolved before initialize_tags so an invalid config.info fails before any conversion runs.
19
+ info = openapi_info
18
20
  initialize_tags
19
21
 
20
22
  {
21
23
  openapi: '3.0.0',
22
- info: Gitlab::GrapeOpenapi.configuration.info.to_h,
24
+ info: info,
23
25
  tags: tag_registry.tags.sort_by { |t| t.fetch(:name, '') },
24
26
  servers: Gitlab::GrapeOpenapi.configuration.servers.map(&:to_h),
25
27
  paths: paths,
@@ -50,9 +52,37 @@ module Gitlab
50
52
 
51
53
  private
52
54
 
55
+ def openapi_info
56
+ hash = configured_info.to_h
57
+ return hash unless blank?(hash[:title]) || blank?(hash[:version])
58
+
59
+ raise ConfigurationError, "config.info must be set with at least a title and version"
60
+ end
61
+
62
+ def configured_info
63
+ info = Gitlab::GrapeOpenapi.configuration.info
64
+
65
+ case info
66
+ when Models::Info then info
67
+ when Hash then Models::Info.new(**info.transform_keys(&:to_sym))
68
+ when nil then Models::Info.new
69
+ else
70
+ raise ConfigurationError,
71
+ "config.info must be a Gitlab::GrapeOpenapi::Models::Info or Hash, got #{info.class}"
72
+ end
73
+ end
74
+
75
+ def blank?(value)
76
+ value.to_s.strip.empty?
77
+ end
78
+
53
79
  def schemas
54
80
  entity_schemas = @schema_registry.schemas.transform_values(&:to_h)
55
81
  request_body_schemas = @request_body_registry.schemas
82
+
83
+ collisions = entity_schemas.keys & request_body_schemas.keys
84
+ raise ArgumentError, "Schema component name collision: #{collisions.join(', ')}" unless collisions.empty?
85
+
56
86
  entity_schemas.merge(request_body_schemas)
57
87
  end
58
88
  end
@@ -4,6 +4,8 @@ module Gitlab
4
4
  module GrapeOpenapi
5
5
  module Models
6
6
  class Parameter
7
+ include Concerns::Serializable
8
+
7
9
  # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#parameter-object
8
10
  attr_reader :name, :required, :in_value, :description, :options, :schema, :example
9
11
  attr_accessor :style, :explode
@@ -17,7 +19,7 @@ module Gitlab
17
19
  @description = options[:desc]
18
20
  @schema = schema
19
21
  @in_value = in_value
20
- @example = options.dig(:documentation, :example)
22
+ @example = stringify_symbols(options.dig(:documentation, :example))
21
23
  @default = options.dig(:documentation, :default)
22
24
  @style = nil
23
25
  @explode = nil
@@ -129,7 +129,7 @@ module Gitlab
129
129
 
130
130
  def build_enum_schema(object_type)
131
131
  schema = { type: object_type }
132
- schema[:enum] = param_options[:values] unless param_options[:values].is_a?(Proc)
132
+ schema[:enum] = stringify_symbols(param_options[:values]) unless param_options[:values].is_a?(Proc)
133
133
  schema[:description] = annotated_description if param_options[:desc]
134
134
  schema
135
135
  end
@@ -203,7 +203,7 @@ module Gitlab
203
203
  schema[:description] = annotated_description if param_options[:desc]
204
204
 
205
205
  if param_options.dig(:documentation, :example)
206
- schema[:example] = param_options.dig(:documentation, :example)
206
+ schema[:example] = stringify_symbols(param_options.dig(:documentation, :example))
207
207
  end
208
208
 
209
209
  # Add regex validations
@@ -9,7 +9,7 @@ module Gitlab
9
9
 
10
10
  def initialize(
11
11
  status_code:, description:, entity_class:, headers: {}, content_type: 'application/json',
12
- example: nil, examples: nil)
12
+ example: nil, examples: nil, is_array: false)
13
13
  @status_code = status_code.to_s
14
14
  @description = description
15
15
  @entity_class = entity_class
@@ -17,6 +17,7 @@ module Gitlab
17
17
  @content_type = content_type
18
18
  @example = example
19
19
  @examples = examples
20
+ @is_array = is_array
20
21
  end
21
22
 
22
23
  def to_h(schema_registry)
@@ -24,7 +25,7 @@ module Gitlab
24
25
  description: description,
25
26
  content: {
26
27
  content_type => {
27
- schema: { '$ref' => schema_ref(schema_registry) },
28
+ schema: schema(schema_registry),
28
29
  example: @example,
29
30
  examples: @examples
30
31
  }.compact
@@ -38,6 +39,15 @@ module Gitlab
38
39
 
39
40
  private
40
41
 
42
+ # `is_array: true` on a `success`/`entity` declaration means the route
43
+ # renders a collection of the entity, not a single instance.
44
+ def schema(schema_registry)
45
+ reference = { '$ref' => schema_ref(schema_registry) }
46
+ return reference unless @is_array
47
+
48
+ { type: 'array', items: reference }
49
+ end
50
+
41
51
  def schema_ref(schema_registry)
42
52
  normalized_name = schema_registry.register(entity_class, nil)
43
53
  "#/components/schemas/#{normalized_name}"
@@ -0,0 +1,24 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Gitlab
4
+ module GrapeOpenapi
5
+ class OperationIdRegistry
6
+ def initialize
7
+ @operation_ids = {}
8
+ end
9
+
10
+ def register(candidate)
11
+ operation_id = candidate
12
+ suffix = 2
13
+
14
+ while @operation_ids.key?(operation_id)
15
+ operation_id = "#{candidate}_#{suffix}"
16
+ suffix += 1
17
+ end
18
+
19
+ @operation_ids[operation_id] = true
20
+ operation_id
21
+ end
22
+ end
23
+ end
24
+ end
@@ -1,7 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'openssl'
4
-
5
3
  module Gitlab
6
4
  module GrapeOpenapi
7
5
  class RequestBodyRegistry
@@ -11,47 +9,19 @@ module Gitlab
11
9
 
12
10
  def initialize
13
11
  @schemas = {}
14
- @schema_hashes = {}
15
12
  end
16
13
 
17
- def register(schema)
14
+ def register(schema, name:)
18
15
  return nil if schema.blank?
19
16
 
20
- schema_hash = compute_hash(schema)
21
-
22
- if @schema_hashes.key?(schema_hash)
23
- existing_name = @schema_hashes[schema_hash]
24
- return { '$ref' => "#{SCHEMA_PATH_PREFIX}#{existing_name}" }
17
+ if @schemas.key?(name) && @schemas[name] != schema
18
+ raise ArgumentError, "Request body schema name '#{name}' is already registered"
25
19
  end
26
20
 
27
- name = "RequestBody_#{short_hash(schema_hash)}"
28
21
  @schemas[name] = schema
29
- @schema_hashes[schema_hash] = name
30
22
 
31
23
  { '$ref' => "#{SCHEMA_PATH_PREFIX}#{name}" }
32
24
  end
33
-
34
- private
35
-
36
- def compute_hash(schema)
37
- normalized = normalize_for_hash(schema)
38
- OpenSSL::Digest::SHA256.hexdigest(normalized.to_s)
39
- end
40
-
41
- def short_hash(full_hash)
42
- full_hash[0, 12]
43
- end
44
-
45
- def normalize_for_hash(obj)
46
- case obj
47
- when Hash
48
- obj.sort.map { |k, v| [k.to_s, normalize_for_hash(v)] }
49
- when Array
50
- obj.map { |v| normalize_for_hash(v) }
51
- else
52
- obj
53
- end
54
- end
55
25
  end
56
26
  end
57
27
  end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Gitlab
4
4
  module GrapeOpenapi
5
- VERSION = "0.5.0"
5
+ VERSION = "0.7.0"
6
6
  end
7
7
  end
@@ -6,6 +6,7 @@ require_relative "gitlab/grape_openapi/configuration"
6
6
  require_relative "gitlab/grape_openapi/generator"
7
7
  require_relative "gitlab/grape_openapi/schema_registry"
8
8
  require_relative "gitlab/grape_openapi/request_body_registry"
9
+ require_relative "gitlab/grape_openapi/operation_id_registry"
9
10
  require_relative "gitlab/grape_openapi/tag_registry"
10
11
  require_relative "gitlab/grape_openapi/normalized_path"
11
12
 
@@ -51,6 +52,9 @@ module Gitlab
51
52
  module GrapeOpenapi
52
53
  GenerationError = Class.new(StandardError)
53
54
 
55
+ # Raised when `config.info` is missing a title or version.
56
+ ConfigurationError = Class.new(GenerationError)
57
+
54
58
  # Raised when a route declares more than one optional path segment
55
59
  # containing a named parameter (e.g. `/foo(/:a)/bar(/:b)`).
56
60
  MultipleOptionalSegmentsError = Class.new(GenerationError)
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: gitlab-grape-openapi
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - group::api
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-09-03 00:00:00.000000000 Z
11
+ date: 2026-10-02 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: grape
@@ -172,6 +172,7 @@ files:
172
172
  - lib/gitlab/grape_openapi/models/server_variable.rb
173
173
  - lib/gitlab/grape_openapi/models/tag.rb
174
174
  - lib/gitlab/grape_openapi/normalized_path.rb
175
+ - lib/gitlab/grape_openapi/operation_id_registry.rb
175
176
  - lib/gitlab/grape_openapi/request_body_registry.rb
176
177
  - lib/gitlab/grape_openapi/schema_registry.rb
177
178
  - lib/gitlab/grape_openapi/serializers/time.rb