gitlab-grape-openapi 0.9.0 → 0.10.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:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: baf765aa19cd584ef90ebbeae24fcdf4027ae8d8e4f1bb108bc54b72bbf19a73
|
|
4
|
+
data.tar.gz: 300cca6362ed4795b834ab123648a250ee4f514ba207edcb402caa1e9020c615
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 46046c44247a31ab9d7ed9a481999b9227ae13597da907796e0f2b9dc0be8ddb322ccb5e03c7baf214e710bac033ac60eb7f3d1ec6297d73edcddd5d97f9b614
|
|
7
|
+
data.tar.gz: 56735aa0a8fb9b9a9f09d22557b3d08cf74035f2d3bf567d2c0782755c9d6cdb3aecd37f34ae9974e6059306daf7ca9ef163f2981c298ff62e2a521e88ccafad
|
data/README.md
CHANGED
|
@@ -25,6 +25,7 @@ Internal gem for generating [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.0)
|
|
|
25
25
|
- [Annotations](#annotations)
|
|
26
26
|
- [Usage](#usage)
|
|
27
27
|
- [Generating an OpenAPI Specification](#generating-an-openapi-specification)
|
|
28
|
+
- [Listing documented routes](#listing-documented-routes)
|
|
28
29
|
- [Usage with `gitlab-org/gitlab`](#usage-with-gitlab-orggitlab)
|
|
29
30
|
- [Architecture](#architecture)
|
|
30
31
|
- [Parameter constraints](#parameter-constraints)
|
|
@@ -188,6 +189,24 @@ require 'yaml'
|
|
|
188
189
|
File.write('openapi.yaml', spec.to_yaml)
|
|
189
190
|
```
|
|
190
191
|
|
|
192
|
+
### Listing documented routes
|
|
193
|
+
|
|
194
|
+
`documented_routes` returns the Grape routes whose method and path `generate` documents, given the same `api_classes`.
|
|
195
|
+
It leaves out routes of classes in `excluded_api_classes`, routes marked `hidden true`, and Grape's catch-all route.
|
|
196
|
+
The routes do not map one-to-one to operations:
|
|
197
|
+
|
|
198
|
+
- Routes with the same method whose paths differ only by parameter name (`/things/:id` and `/things/:name`)
|
|
199
|
+
are all returned, but `generate` emits one operation for them, built from the last route.
|
|
200
|
+
- A route with an optional path segment that holds a named parameter is returned once, but `generate` emits an operation for each variant.
|
|
201
|
+
For more information, see [Optional path segments](#optional-path-segments).
|
|
202
|
+
|
|
203
|
+
Use it to check which routes are missing from the specification without matching paths in the generated document:
|
|
204
|
+
|
|
205
|
+
```ruby
|
|
206
|
+
documented = Gitlab::GrapeOpenapi.documented_routes(api_classes: api_classes)
|
|
207
|
+
undocumented = api_classes.flat_map(&:routes) - documented
|
|
208
|
+
```
|
|
209
|
+
|
|
191
210
|
### Usage with `gitlab-org/gitlab`
|
|
192
211
|
|
|
193
212
|
1. Start a Rails console in your GDK:
|
|
@@ -27,6 +27,25 @@ module Gitlab
|
|
|
27
27
|
new(routes, schema_registry, request_body_registry).convert
|
|
28
28
|
end
|
|
29
29
|
|
|
30
|
+
def self.skip_route?(route)
|
|
31
|
+
# Hidden routes (declared with `hidden true`) must be skipped before
|
|
32
|
+
# OperationConverter runs. Otherwise it pollutes the shared schema and
|
|
33
|
+
# request-body registries with entries that no emitted operation references,
|
|
34
|
+
# surfacing as `no-unused-components` warnings under `components.schemas`.
|
|
35
|
+
return true if route.options.dig(:settings, :description, :hidden)
|
|
36
|
+
|
|
37
|
+
# Grape's catch-all (`route :any, '*path'`) is an internal routing artifact,
|
|
38
|
+
# not an API endpoint, and * isn't a valid HTTP method. Grape itself
|
|
39
|
+
# discriminates it by request method - see `collect_route_config_per_pattern`
|
|
40
|
+
# in `grape/api/instance.rb` - so match on the method alone.
|
|
41
|
+
#
|
|
42
|
+
# Do NOT also skip paths containing `*`. Splat segments are declared by
|
|
43
|
+
# developers for path segments that may contain slashes (`*module_name`,
|
|
44
|
+
# `*package_name`), and they are real endpoints. NormalizedPath renders them
|
|
45
|
+
# as ordinary `{name}` placeholders. See issue #22.
|
|
46
|
+
route.request_method == '*'
|
|
47
|
+
end
|
|
48
|
+
|
|
30
49
|
def initialize(routes, schema_registry, request_body_registry)
|
|
31
50
|
@routes = routes
|
|
32
51
|
@schema_registry = schema_registry
|
|
@@ -58,7 +77,7 @@ module Gitlab
|
|
|
58
77
|
groups = {}
|
|
59
78
|
|
|
60
79
|
routes.each do |route|
|
|
61
|
-
next if skip_route?(route)
|
|
80
|
+
next if self.class.skip_route?(route)
|
|
62
81
|
|
|
63
82
|
register_route_entities(route)
|
|
64
83
|
|
|
@@ -97,29 +116,6 @@ module Gitlab
|
|
|
97
116
|
end
|
|
98
117
|
end
|
|
99
118
|
|
|
100
|
-
def skip_route?(route)
|
|
101
|
-
# Hidden routes (declared with `hidden true`) must be skipped before
|
|
102
|
-
# OperationConverter runs. Otherwise it pollutes the shared schema and
|
|
103
|
-
# request-body registries with entries that no emitted operation references,
|
|
104
|
-
# surfacing as `no-unused-components` warnings under `components.schemas`.
|
|
105
|
-
return true if hidden?(route)
|
|
106
|
-
|
|
107
|
-
# Grape's catch-all (`route :any, '*path'`) is an internal routing artifact,
|
|
108
|
-
# not an API endpoint, and * isn't a valid HTTP method. Grape itself
|
|
109
|
-
# discriminates it by request method - see `collect_route_config_per_pattern`
|
|
110
|
-
# in `grape/api/instance.rb` - so match on the method alone.
|
|
111
|
-
#
|
|
112
|
-
# Do NOT also skip paths containing `*`. Splat segments are declared by
|
|
113
|
-
# developers for path segments that may contain slashes (`*module_name`,
|
|
114
|
-
# `*package_name`), and they are real endpoints. NormalizedPath renders them
|
|
115
|
-
# as ordinary `{name}` placeholders. See issue #22.
|
|
116
|
-
extract_method(route) == '*'
|
|
117
|
-
end
|
|
118
|
-
|
|
119
|
-
def hidden?(route)
|
|
120
|
-
!!route.options.dig(:settings, :description, :hidden)
|
|
121
|
-
end
|
|
122
|
-
|
|
123
119
|
def normalize_path(route)
|
|
124
120
|
NormalizedPath.new(route.pattern.origin).to_s.gsub('{version}', config.api_version)
|
|
125
121
|
end
|
|
@@ -212,7 +208,7 @@ module Gitlab
|
|
|
212
208
|
# child route's own `options[:params]`).
|
|
213
209
|
def register_inherited_path_params
|
|
214
210
|
routes.each do |route|
|
|
215
|
-
next if skip_route?(route)
|
|
211
|
+
next if self.class.skip_route?(route)
|
|
216
212
|
|
|
217
213
|
declared = route.options[:params] || {}
|
|
218
214
|
next if declared.empty?
|
|
@@ -50,6 +50,10 @@ module Gitlab
|
|
|
50
50
|
Converters::PathConverter.convert(all_routes, @schema_registry, @request_body_registry)
|
|
51
51
|
end
|
|
52
52
|
|
|
53
|
+
def documented_routes
|
|
54
|
+
@api_classes.flat_map(&:routes).reject { |route| Converters::PathConverter.skip_route?(route) }
|
|
55
|
+
end
|
|
56
|
+
|
|
53
57
|
private
|
|
54
58
|
|
|
55
59
|
def openapi_info
|
data/lib/gitlab-grape-openapi.rb
CHANGED
|
@@ -79,6 +79,12 @@ module Gitlab
|
|
|
79
79
|
def generate(options = {})
|
|
80
80
|
Generator.new(options).generate
|
|
81
81
|
end
|
|
82
|
+
|
|
83
|
+
# The Grape routes whose method and path `generate` documents, given the same `api_classes`.
|
|
84
|
+
# Not one-to-one with operations: see "Listing documented routes" in README.md.
|
|
85
|
+
def documented_routes(options = {})
|
|
86
|
+
Generator.new(options).documented_routes
|
|
87
|
+
end
|
|
82
88
|
end
|
|
83
89
|
end
|
|
84
90
|
end
|
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.10.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-
|
|
11
|
+
date: 2026-11-18 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: grape
|