gitlab-grape-openapi 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe58f8cf04c60643bf6474aa80def52213a8f5147f1fd96a41a557a7b011a841
-  data.tar.gz: caea075647208bd681e48d1751a6722f6a86e934f82624b710bd89eb7d225b7b
+  metadata.gz: 79aec4f1d4657df18a7ccbcf6b689c9f00f8f0b5c940d508da34b05112aa8432
+  data.tar.gz: 275e4524ae0d61929af41ca0540ff080f49790f0a2cbb1308f4a0e6d6b79f75f
 SHA512:
-  metadata.gz: ca754c4b4e7a5a4de99cd913facf2b55d4eee9f95d3be48b65540fc7e0a46fe6691651d3c7bfbae6ece7ba281fb332b10408a917ee0bdc47026c310761eeab97
-  data.tar.gz: c6ad6d03370a62f21a5fa55f071e01cd2b170e0e87ed282b4d62654c56e56f3743698ab7a63f846655bb7f9dca4d0cda2348a0a5ce7100c68bb8c4b08759c8c4
+  metadata.gz: cd0dfaa149fb09c6a61bd2b8c9256d506e6bc62da716faed13e9b0c2f48932efed53b69315c330d1f91f8bf550bb5728fc284865748966b39f15b4a7d7598c67
+  data.tar.gz: c937af8a3e5f1a4f80ae412e7d444f1b11c7d30268b5c64dd9441c3e2b6125db1b325387effa1ec917821211ee12ca7e140dd1f9e659bcab039c86d99c3e3db4

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,77 @@ 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)
+
+            required = required_exposure_keys(root_exposures)
+            schema.required = required if required.any?
           end
         end
 
-        def build_properties
-          root_exposures.each_with_object({}) do |exposure, properties|
+        def required_exposure_keys(exposures)
+          exposures.flat_map do |exposure|
+            if inlineable_merge_exposure?(exposure)
+              # Merged entity properties become the parent's, so their
+              # `required` entries do too.
+              build_or_fetch_nested_schema(nested_entity_class(exposure))&.required || []
+            elsif block_exposure?(exposure) && exposure.for_merge
+              required_exposure_keys(exposure.nested_exposures)
+            elsif exposure_documentation(exposure)[:required]
+              [exposure.key.to_s]
+            else
+              []
+            end
+          end.uniq
+        end
+
+        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?
+
+          nested_required = required_exposure_keys(exposure.nested_exposures)
+          object_schema[:required] = nested_required if nested_required.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
 
@@ -137,11 +191,23 @@ module Gitlab
             type: TypeResolver.resolve_type(actual_type) || DEFAULT_TYPE,
             description: documentation[:desc],
             format: TypeResolver.resolve_format(documentation[:format], actual_type),
+            enum: enum_values(documentation),
             default: default_value,
             example: documentation[:example]
           }
         end
 
+        # `values:` may also be a Proc or a Range (runtime validation
+        # constructs); only a literal Array translates to a fixed OpenAPI
+        # enum. Mirrors `ParameterConverter#build_enum_schema`. Symbols are
+        # stringified because the response contains strings, not symbols.
+        def enum_values(documentation)
+          values = documentation[:values]
+          return unless values.is_a?(Array) && values.any?
+
+          values.map { |value| value.is_a?(Symbol) ? value.to_s : value }
+        end
+
         def build_type_schema(type, documentation)
           schema = { type: TypeResolver.resolve_type(type) || DEFAULT_TYPE }
 
@@ -197,10 +263,13 @@ module Gitlab
         def build_primitive_items(property, item_type)
           items = { type: item_type }
 
-          # Move format to items if present
-          if property[:format]
-            items[:format] = property[:format]
-            property[:format] = nil
+          # Move format and enum to items if present; they constrain each
+          # element, not the array itself
+          [:format, :enum].each do |key|
+            next unless property[key]
+
+            items[key] = property[key]
+            property[key] = nil
           end
 
           items

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
@@ -228,17 +238,10 @@ module Gitlab
         # Looks something like:
         # [{:attributes=>[:version_prefix],
         #   :options=>/^[\d+.]+/,
-        #   :required=>false,
-        #   :params_scope=>#<Grape::Validations::ParamsScope:0x000000016dc35820
-        #   :opts=>{:allow_blank=>nil, :fail_fast=>false},
+        #   :opts=>{:fail_fast=>false},
         #   :validator_class=>Grape::Validations::Validators::RegexpValidator}]
         def validations_for(attribute)
-          route
-            .app
-            .inheritable_setting
-            .namespace_stackable
-            .new_values[:validations]
-            &.select { |v| v[:attributes].include?(attribute) }
+          GrapeCompat.validations_for(route, attribute)
         end
 
         def extract_request_body

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/grape_compat.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    # Isolates the Grape internals this gem reads so version differences live in
+    # one place.
+    #
+    # Grape < 3.2 stores each declared validation as a Hash; Grape >= 3.2 stores
+    # a frozen validator instance instead (ruby-grape/grape#2657). Both shapes
+    # are normalized to the Hash the converters expect.
+    module GrapeCompat
+      class << self
+        # Declared validations for a single attribute, newest scope only.
+        #
+        # Reads `new_values` rather than `[]` or `route[:saved_validations]` on
+        # purpose: those also include validations inherited from parent scopes,
+        # which would change the generated output.
+        def validations_for(route, attribute)
+          validations = route.app.inheritable_setting.namespace_stackable.new_values[:validations]
+          return unless validations
+
+          validations.filter_map do |validation|
+            normalized = normalize(validation)
+            normalized if normalized && normalized[:attributes].include?(attribute)
+          end
+        end
+
+        private
+
+        def normalize(validation)
+          return validation if validation.is_a?(Hash)
+
+          # Grape 3.2's ContractScopeValidator declares no attributes, so it maps
+          # to no parameter.
+          return unless validation.respond_to?(:attrs)
+
+          {
+            attributes: validation.attrs,
+            validator_class: validation.class,
+            # Grape 3.2 exposes no public reader for the validator options, which
+            # carry regexp patterns and limits. Switch to the reader if one is
+            # added upstream.
+            options: validation.instance_variable_get(:@options),
+            opts: { fail_fast: validation.fail_fast? }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/models/request_body/parameter_schema.rb

@@ -226,12 +226,7 @@ module Gitlab
           end
 
           def validations_for(attribute)
-            route
-              .app
-              .inheritable_setting
-              .namespace_stackable
-              .new_values[:validations]
-              &.select { |v| v[:attributes].include?(attribute) }
+            GrapeCompat.validations_for(route, attribute)
           end
 
           def apply_allow_blank(schema)

data/lib/gitlab/grape_openapi/models/schema.rb

@@ -5,7 +5,7 @@ module Gitlab
     module Models
       # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schema-object
       class Schema
-        attr_accessor :properties, :type
+        attr_accessor :properties, :required, :type
 
         def initialize
           @properties = {}
@@ -31,6 +31,7 @@ module Gitlab
           {}.tap do |hash|
             add_type(hash)
             add_properties(hash)
+            add_required(hash)
           end
         end
 
@@ -44,6 +45,10 @@ module Gitlab
           hash[:properties] = properties.transform_values(&:to_h)
         end
 
+        def add_required(hash)
+          hash[:required] = required if required && !required.empty?
+        end
+
         def description
           @properties[:description]
         end

data/lib/gitlab/grape_openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module GrapeOpenapi
-    VERSION = "0.2.2"
+    VERSION = "0.3.0"
   end
 end

data/lib/gitlab-grape-openapi.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "gitlab/grape_openapi/version"
+require_relative "gitlab/grape_openapi/grape_compat"
 require_relative "gitlab/grape_openapi/configuration"
 require_relative "gitlab/grape_openapi/generator"
 require_relative "gitlab/grape_openapi/schema_registry"
@@ -45,6 +46,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,29 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-grape-openapi
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - group::api
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-16 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: grape-entity
   requirement: !ruby/object:Gem::Requirement
@@ -148,6 +154,7 @@ files:
 - lib/gitlab/grape_openapi/converters/tag_converter.rb
 - lib/gitlab/grape_openapi/converters/type_resolver.rb
 - lib/gitlab/grape_openapi/generator.rb
+- lib/gitlab/grape_openapi/grape_compat.rb
 - lib/gitlab/grape_openapi/models/info.rb
 - lib/gitlab/grape_openapi/models/operation.rb
 - lib/gitlab/grape_openapi/models/parameter.rb