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: a9e63791bdf9de237dc4f38df23bb3cc877fa66e23f6a62cc877504937bb6253
4
- data.tar.gz: d4ab0c3f65fde3c4ee4ade74f93155f0bdc920110b804721049306963c82fda8
3
+ metadata.gz: baf765aa19cd584ef90ebbeae24fcdf4027ae8d8e4f1bb108bc54b72bbf19a73
4
+ data.tar.gz: 300cca6362ed4795b834ab123648a250ee4f514ba207edcb402caa1e9020c615
5
5
  SHA512:
6
- metadata.gz: 0a381afb3ce0bdc4fedcba33a68d631c9d00103afc124e0f67d66d4e2ae51f6c9450529eae54e0b501a62c826ad5d47fae3b8738712c2923db27cfc700dcacf6
7
- data.tar.gz: b6fc6c04f49e0afbd19812b2fc7ef2b07ef11091d147655501acbf545cf0a0339922bdd9d7bbbc85305f90b41d84ae15fa84c228b75933413ca230fa0e59329f
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
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Gitlab
4
4
  module GrapeOpenapi
5
- VERSION = "0.9.0"
5
+ VERSION = "0.10.0"
6
6
  end
7
7
  end
@@ -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.9.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-16 00:00:00.000000000 Z
11
+ date: 2026-11-18 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: grape