gitlab-grape-openapi 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edcdc6aad3dda3c3aee4a30f682dd547c87d5606b8f6a29bbc132230c8e51176
-  data.tar.gz: 5d51d13a6a07d747535f51b1a5adcb5dbf4ce9da20085ddc3eafb6721cdd4ec9
+  metadata.gz: 6b3783b6b78454e5f8a76c0f2da60864f1f890272e8d9604cac6c0152becea17
+  data.tar.gz: 21b5cec8a2792e118c480334b358aa62d3fc4d85553fbbe7ace7871a7fc91709
 SHA512:
-  metadata.gz: 92c6f934a4207b4156b8cb5a7c4db3bb502ef2c774246baefa9e33f69429671ddfcc427a0c45a9b34898beba1fa9f5df203d7fda6a26dd2fd860ba82c7d81502
-  data.tar.gz: ba53cc8fd5235fe8ffc9d43d9d5133855bd4384aed3c928b1b4146125da9e54829d7302051dc7cd7bc0fd16040973c091e307a5338a6b503ad9e2fdbc8b5c801
+  metadata.gz: 36ca996cdcbb0a74ac4853fe174491ffbdb38176952155630b956d9dcef42da63a7e1403693e54b3db27689590e20acdc6989cf0af5d288e96c5e692e5c110c8
+  data.tar.gz: 461ddbe6f58280b0678e394f20f722bb981e0cdb2c0684456597b5deff382e18ed96df69753df729e6e1e1cea73107eeaad9c4cff37a79aa2a92bb5b189948eb

data/README.md

@@ -194,6 +194,29 @@ Generator
 - **RequestBodyRegistry** - Tracks request body schemas
 - **TagRegistry** - Tracks API tags
 
+### Optional path segments
+
+Grape lets a route mark a path segment as optional with parentheses, e.g.
+`resource '/settings_sync(/:settings_context_hash)'`. Such a route genuinely
+accepts requests both with and without the segment, but a single OpenAPI path
+key cannot express that optionality — an OpenAPI path parameter is always
+`required: true`.
+
+When a route contains **one** optional segment that holds a named parameter,
+`PathConverter` fans it out into two OpenAPI paths:
+
+- a **collapsed** path with the segment and its parameter removed entirely
+  (the parameter is absent from `parameters`, not marked optional), and
+- an **expanded** path where the parameter is present as a required
+  `in: path` parameter.
+
+Each variant gets its own `operationId`, so both remain unique. Optional
+segments without a named parameter (e.g. `(-/)`) are left unchanged.
+
+Generating the combinatorial set of paths for routes with more than one
+param-bearing optional segment is **not** supported: such a route raises
+`Gitlab::GrapeOpenapi::MultipleOptionalSegmentsError`.
+
 ## Development
 
 ```bash

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

@@ -53,23 +53,55 @@ module Gitlab
         def build_schema
           Models::Schema.new.tap do |schema|
             schema.type = OBJECT_TYPE
-            schema.properties = build_properties
+            schema.properties = build_exposures_properties(root_exposures)
           end
         end
 
-        def build_properties
-          root_exposures.each_with_object({}) do |exposure, properties|
+        def build_exposures_properties(exposures)
+          exposures.each_with_object({}) do |exposure, properties|
             if inlineable_merge_exposure?(exposure)
               # `merge: true` flattens the nested entity's exposures into the
               # parent at runtime. Inline its properties instead of emitting a
               # `$ref`, so the generated schema reflects the actual response.
               inline_merged_properties!(properties, exposure)
+            elsif block_exposure?(exposure)
+              add_block_exposure_properties!(properties, exposure)
             else
               properties[exposure.key] = build_property(exposure)
             end
           end
         end
 
+        # Grouping blocks (`expose :foo do ... end`) are NestingExposure
+        # instances. Blocks that compute a value (`expose(:foo) { |obj, _| }`)
+        # are BlockExposure and fall through to the default handling.
+        def block_exposure?(exposure)
+          exposure.is_a?(Grape::Entity::Exposure::NestingExposure)
+        end
+
+        def add_block_exposure_properties!(properties, exposure)
+          if exposure.for_merge
+            # A `merge: true` block merges its nested hash into the parent at
+            # runtime, so its key never appears in the response.
+            properties.merge!(build_exposures_properties(exposure.nested_exposures))
+          else
+            properties[exposure.key] = build_block_property(exposure)
+          end
+        end
+
+        def build_block_property(exposure)
+          documentation = exposure_documentation(exposure)
+          nested_properties = build_exposures_properties(exposure.nested_exposures)
+          object_schema = { type: OBJECT_TYPE }
+          object_schema[:properties] = nested_properties if nested_properties.any?
+
+          if documentation[:is_array]
+            { type: ARRAY_TYPE, description: documentation[:desc], items: object_schema }.compact
+          else
+            object_schema.merge(description: documentation[:desc]).compact
+          end
+        end
+
         def inlineable_merge_exposure?(exposure)
           return false unless exposure.for_merge
 

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

@@ -8,20 +8,29 @@ module Gitlab
 
         DASH_SEGMENT = 'Dash'
 
-        def self.convert(route, schema_registry, request_body_registry, inherited_path_params: {})
+        def self.convert(
+          route, schema_registry, request_body_registry, inherited_path_params: {},
+          path_override: nil, removed_params: [])
           new(
             route,
             schema_registry,
             request_body_registry,
-            inherited_path_params: inherited_path_params
+            inherited_path_params: inherited_path_params,
+            path_override: path_override,
+            removed_params: removed_params
           ).convert
         end
 
-        def initialize(route, schema_registry, request_body_registry, inherited_path_params: {})
+        def initialize(
+          route, schema_registry, request_body_registry, inherited_path_params: {},
+          path_override: nil, removed_params: [])
           @route = route
           @schema_registry = schema_registry
           @request_body_registry = request_body_registry
           @inherited_path_params = inherited_path_params
+          # @path_override and @removed_params are set together when optional-path-segment variants exist
+          @path_override = path_override
+          @removed_params = removed_params
           @config = Gitlab::GrapeOpenapi.configuration
           @options = route.options
           @pattern = route.pattern
@@ -46,7 +55,7 @@ module Gitlab
         private
 
         attr_reader :config, :route, :options, :pattern, :endpoint, :schema_registry, :request_body_registry,
-          :inherited_path_params
+          :inherited_path_params, :path_override, :removed_params
 
         def route_method
           @route.request_method
@@ -78,7 +87,11 @@ module Gitlab
                      end
                    end
 
-          inject_missing_path_parameters(params)
+          params = inject_missing_path_parameters(params)
+          return params if removed_params.empty?
+
+          removed = removed_params.map(&:to_s)
+          params.reject { |param| removed.include?(param.name.to_s) }
         end
 
         def inject_missing_path_parameters(params)
@@ -201,10 +214,7 @@ module Gitlab
         end
 
         def normalized_path
-          @normalized_path ||= begin
-            path = normalize_path_pattern
-            path.gsub('{version}', config.api_version)
-          end
+          @normalized_path ||= path_override || normalize_path_pattern.gsub('{version}', config.api_version)
         end
 
         def normalize_path_pattern

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

@@ -25,8 +25,8 @@ module Gitlab
 
         def in_value
           # Strip only the :version path segment (not substrings like :version_id or :package_version),
-          # then match the param name as a complete segment bounded by / . ( or end-of-string.
-          route.path.gsub('/:version/', '/').match?(%r{/:#{Regexp.escape(name)}([/.(]|$)}) ? 'path' : 'query'
+          # then match the param name as a complete segment bounded by / . ( ) or end-of-string.
+          route.path.gsub('/:version/', '/').match?(%r{/:#{Regexp.escape(name)}([/.()]|$)}) ? 'path' : 'query'
         end
 
         def example

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

@@ -10,6 +10,12 @@ module Gitlab
         # handles all three shapes (Class, Hash with :model, Array of those).
         RESPONSE_DECLARATIONS = %i[entity success].freeze
 
+        # A Grape optional path segment: a parenthesised group, e.g. `(/:id)`.
+        OPTIONAL_SEGMENT = /\(([^()]*)\)/
+
+        # Optional path segment variants are each represented in the OpenAPI spec as a unique path.
+        PathVariant = Struct.new(:key, :path_override, :removed_params)
+
         def self.convert(routes, schema_registry, request_body_registry)
           new(routes, schema_registry, request_body_registry).convert
         end
@@ -25,8 +31,12 @@ module Gitlab
         def convert
           register_inherited_path_params
 
-          paths = grouped_routes.transform_values do |routes_for_path|
-            build_path_item(routes_for_path)
+          paths = {}
+          grouped_routes.each do |path_key, routes_for_path|
+            path_variants(path_key, routes_for_path.first).each do |variant|
+              paths[variant.key] ||= {}
+              paths[variant.key].merge!(build_path_item(routes_for_path, variant))
+            end
           end
 
           paths.reject { |_path, operations| operations.empty? }
@@ -100,7 +110,7 @@ module Gitlab
           normalize_path(route).gsub(/\{[^}]+\}/, '{param}')
         end
 
-        def build_path_item(routes_for_path)
+        def build_path_item(routes_for_path, variant)
           path_item = Models::PathItem.new
 
           routes_for_path.each do |route|
@@ -108,7 +118,9 @@ module Gitlab
               route,
               schema_registry,
               request_body_registry,
-              inherited_path_params: inherited_path_params
+              inherited_path_params: inherited_path_params,
+              path_override: variant.path_override,
+              removed_params: variant.removed_params
             )
             method = extract_method(route)
             path_item.add_operation(method, operation)
@@ -117,6 +129,38 @@ module Gitlab
           path_item.to_h
         end
 
+        # Expand a grouped path key into the OpenAPI paths it maps to.
+        #
+        # A single OpenAPI path key cannot express Grape's optional segments,
+        # so a route with one param-bearing optional segment fans out into two
+        # keys: a collapsed variant (segment and param removed entirely) and an
+        # expanded variant (param present, rendered as a required path param).
+        # Routes without such a segment yield a single, unchanged variant.
+        def path_variants(path_key, route)
+          param_groups = path_key.scan(OPTIONAL_SEGMENT).flatten.select { |inner| inner.match?(/\{\w+\}/) }
+
+          raise MultipleOptionalSegmentsError, multi_segment_message(route, path_key) if param_groups.length > 1
+
+          inner = param_groups.first
+          return [PathVariant.new(path_key, nil, [])] if inner.nil?
+
+          removed = inner.scan(/\{(\w+)\}/).flatten
+          collapsed = path_key.sub("(#{inner})", '').gsub(%r{//+}, '/').delete_suffix('/')
+          collapsed = '/' if collapsed.empty?
+          expanded = path_key.sub("(#{inner})", inner).gsub(%r{//+}, '/')
+
+          [
+            PathVariant.new(collapsed, collapsed, removed),
+            PathVariant.new(expanded, expanded, [])
+          ]
+        end
+
+        def multi_segment_message(route, path_key)
+          "Route '#{extract_method(route)} #{path_key}' declares more than one optional path segment " \
+            "with a named parameter. gitlab-grape-openapi supports at most one optional segment per route " \
+            "and does not generate the combinatorial set of path variants."
+        end
+
         def extract_method(route)
           route.request_method
         end

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

@@ -38,14 +38,15 @@ module Gitlab
         end
 
         def process_class_entity(entity_class)
-          success_code = infer_success_code
           if EntityConverter.grape_entity?(entity_class)
+            success_code = infer_success_code(with_body: true)
             add_response_with_entity(
               status_code: success_code,
               description: http_status_text(success_code),
               entity_class: entity_class
             )
           else
+            success_code = infer_success_code
             add_simple_response(
               status_code: success_code,
               description: http_status_text(success_code)
@@ -54,20 +55,20 @@ module Gitlab
         end
 
         def process_hash_entity(entity_hash)
-          success_code = infer_success_code
-
           if entity_hash[:model] && EntityConverter.grape_entity?(entity_hash[:model])
+            status_code = entity_hash[:code] || infer_success_code(with_body: true)
             add_response_with_entity(
-              status_code: entity_hash[:code] || success_code,
-              description: entity_hash[:message] || http_status_text(entity_hash[:code] || success_code),
+              status_code: status_code,
+              description: entity_hash[:message] || http_status_text(status_code),
               entity_class: entity_hash[:model],
               example: entity_hash[:example],
               examples: entity_hash[:examples]
             )
           else
+            status_code = entity_hash[:code] || infer_success_code
             add_simple_response(
-              status_code: entity_hash[:code] || success_code,
-              description: entity_hash[:message] || http_status_text(entity_hash[:code] || success_code)
+              status_code: status_code,
+              description: entity_hash[:message] || http_status_text(status_code)
             )
           end
         end
@@ -85,17 +86,19 @@ module Gitlab
 
         def process_array_hash_item(definition)
           if definition[:model] && EntityConverter.grape_entity?(definition[:model])
+            status_code = definition[:code] || infer_success_code(with_body: true)
             add_response_with_entity(
-              status_code: definition[:code] || infer_success_code,
-              description: definition[:message] || http_status_text(definition[:code] || infer_success_code),
+              status_code: status_code,
+              description: definition[:message] || http_status_text(status_code),
               entity_class: definition[:model],
               example: definition[:example],
               examples: definition[:examples]
             )
           else
+            status_code = definition[:code] || infer_success_code
             add_simple_response(
-              status_code: definition[:code] || infer_success_code,
-              description: definition[:message] || http_status_text(definition[:code] || infer_success_code)
+              status_code: status_code,
+              description: definition[:message] || http_status_text(status_code)
             )
           end
         end
@@ -148,10 +151,13 @@ module Gitlab
           end
         end
 
-        def infer_success_code
+        # 204 means "No Content", so it only applies when the response has no
+        # body to document. A DELETE route that renders an entity returns 200
+        # at runtime (Grape's default for a rendered body).
+        def infer_success_code(with_body: false)
           case http_method
           when 'POST' then 201
-          when 'DELETE' then 204
+          when 'DELETE' then with_body ? 200 : 204
           else 200
           end
         end

data/lib/gitlab/grape_openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module GrapeOpenapi
-    VERSION = "0.2.1"
+    VERSION = "0.2.3"
   end
 end

data/lib/gitlab-grape-openapi.rb

@@ -45,6 +45,10 @@ module Gitlab
   module GrapeOpenapi
     GenerationError = Class.new(StandardError)
 
+    # Raised when a route declares more than one optional path segment
+    # containing a named parameter (e.g. `/foo(/:a)/bar(/:b)`).
+    MultipleOptionalSegmentsError = Class.new(GenerationError)
+
     class << self
       attr_writer :configuration
 

metadata

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