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 +4 -4
- data/README.md +95 -11
- data/lib/gitlab/grape_openapi/concerns/constraint_applier.rb +3 -3
- data/lib/gitlab/grape_openapi/concerns/serializable.rb +10 -0
- data/lib/gitlab/grape_openapi/configuration.rb +8 -1
- data/lib/gitlab/grape_openapi/converters/cross_field_validation_resolver.rb +63 -3
- data/lib/gitlab/grape_openapi/converters/entity_converter.rb +7 -5
- data/lib/gitlab/grape_openapi/converters/operation_converter.rb +61 -11
- data/lib/gitlab/grape_openapi/converters/parameter_converter.rb +1 -1
- data/lib/gitlab/grape_openapi/converters/path_converter.rb +6 -2
- data/lib/gitlab/grape_openapi/converters/request_body_converter.rb +7 -5
- data/lib/gitlab/grape_openapi/converters/response_converter.rb +18 -5
- data/lib/gitlab/grape_openapi/generator.rb +31 -1
- data/lib/gitlab/grape_openapi/models/parameter.rb +3 -1
- data/lib/gitlab/grape_openapi/models/request_body/parameter_schema.rb +2 -2
- data/lib/gitlab/grape_openapi/models/response.rb +12 -2
- data/lib/gitlab/grape_openapi/operation_id_registry.rb +24 -0
- data/lib/gitlab/grape_openapi/request_body_registry.rb +3 -33
- data/lib/gitlab/grape_openapi/version.rb +1 -1
- data/lib/gitlab-grape-openapi.rb +4 -0
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b864030f21b5380efa37ccb02b953f5c8d07b2f4d2fe90eb66334e155674e2bc
|
|
4
|
+
data.tar.gz: 37b0f04c277c0b1f1027bdb5f0839f06641a3c6e11fd2e9498cb9a192899914b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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`
|
|
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
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
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).
|
|
203
|
-
|
|
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.
|
|
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`.
|
|
225
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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 =
|
|
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
|
-
|
|
111
|
-
|
|
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
|
-
|
|
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
|
|
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(
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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
|
data/lib/gitlab-grape-openapi.rb
CHANGED
|
@@ -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.
|
|
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-
|
|
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
|