gitlab-grape-openapi 0.0.0 → 0.1.0

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

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class ParameterConverter
+        include CoercerResolver
+        include Concerns::Serializable
+        include Concerns::LimitResolver
+        include Concerns::FailFastAnnotatable
+        include Concerns::RegexConverter
+
+        attr_reader :name, :options, :validations, :route
+
+        def self.convert(name, options:, route:, validations: [])
+          new(name, options: options, validations: validations, route: route).convert
+        end
+
+        def initialize(name, options:, validations:, route:)
+          @name = name
+          @options = options
+          @validations = validations
+          @route = route # Useful for detecting `in` value.
+        end
+
+        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'
+        end
+
+        def example
+          @options.dig(:documentation, :example)
+        end
+
+        def coercer_mapping
+          @coercer_mapping ||= coercer_mapping_for(validations)
+        end
+
+        def schema
+          object_type = TypeResolver.resolve_type(options[:type]) || 'string'
+          object_format = TypeResolver.resolve_format(nil, options[:type])
+          type_str = options[:type].to_s
+
+          mapping = coercer_mapping
+          built_schema = if mapping
+                           build_coerced_schema(mapping)
+                         elsif type_str.start_with?('[') && type_str.exclude?(',')
+                           build_simple_array_schema
+                         elsif type_str.start_with?('[')
+                           build_union_schema(object_type)
+                         elsif options[:values].is_a?(Range)
+                           build_range_schema(object_type)
+                         elsif options[:values]
+                           build_enum_schema(object_type)
+                         elsif array_type?(object_type)
+                           build_array_schema
+                         else
+                           build_basic_schema(object_type, object_format)
+                         end
+
+          apply_allow_blank(built_schema)
+          apply_limit!(built_schema, validations)
+          built_schema
+        end
+
+        def build_simple_array_schema
+          item_type = options[:type].to_s.delete('[').delete(']')
+          { type: 'array', items: { type: TypeResolver.resolve_type(item_type) } }
+        end
+
+        def build_union_schema(object_type)
+          types = object_type[1..-2].split(", ")
+          members = types.map { |type| TypeResolver.resolve_union_member(type) }
+          apply_union_enum!(members)
+          apply_union_default!(members)
+          { oneOf: members }
+        end
+
+        def build_range_schema(object_type)
+          range = options[:values]
+          schema = { type: object_type }
+
+          schema[:minimum] = range.begin if range.begin
+          schema[:maximum] = range.end if range.end
+          schema[:default] = options[:default] if options[:default] && serializable?(options[:default])
+          schema
+        end
+
+        def build_enum_schema(object_type)
+          schema = { type: object_type }
+          schema[:enum] = options[:values] unless options[:values].is_a?(Proc)
+          schema[:default] = options[:default] if options[:default] && serializable?(options[:default])
+          schema
+        end
+
+        def build_array_schema
+          item_type = extract_array_item_type
+          { type: 'array', items: { type: item_type } }
+        end
+
+        def build_basic_schema(object_type, object_format)
+          schema = { type: object_type }
+          schema[:format] = object_format if object_format
+          if options[:default] && serializable?(options[:default])
+            schema[:default] = options[:default]
+          elsif options[:default] &&
+              defined?(ActiveSupport::TimeWithZone) &&
+              options[:default].is_a?(ActiveSupport::TimeWithZone)
+            serialized_default = time_serializer.serialize(options[:default], example: example)
+            schema[:default] = serialized_default if serialized_default
+          end
+
+          add_regex_validations!(schema)
+          schema
+        end
+
+        def array_type?(object_type)
+          object_type.include?('[')
+        end
+
+        def extract_array_item_type
+          options[:type].delete('[').delete(']').downcase
+        end
+
+        def add_regex_validations!(schema)
+          return unless validations
+
+          # Only support one Regex validation per attribute
+          validation = validations&.find { |v| v[:validator_class] == Grape::Validations::Validators::RegexpValidator }
+          return unless validation
+
+          pattern = regexp_to_pattern(validation[:options])
+          schema[:pattern] = pattern if pattern
+        end
+
+        def convert
+          # For requests that can have a request body (POST, PUT, PATCH, etc.), only return a param if it's in the path,
+          # otherwise it'll be a body parameter and shouldn't be included as a query parameter.
+          # GET and DELETE requests don't have request bodies, so all their parameters are included.
+          method = route.request_method
+          return nil if method != 'GET' && method != 'DELETE' && in_value != 'path'
+
+          annotated = options.dup
+          if options[:desc] && fail_fast_in_validations?(validations)
+            annotated[:desc] = annotate_fail_fast(options[:desc])
+          end
+
+          param = Gitlab::GrapeOpenapi::Models::Parameter.new(
+            name,
+            options: annotated,
+            schema: schema,
+            in_value: in_value
+          )
+
+          mapping = coercer_mapping
+          return param unless mapping
+
+          param.style = mapping[:style] if mapping[:style]
+          param.explode = mapping[:explode] if mapping.key?(:explode)
+          param
+        end
+
+        private
+
+        def time_serializer
+          @time_serializer ||= Serializers::Time.new
+        end
+
+        # When a union (oneOf) schema has a `values:` constraint, propagate it
+        # as `enum` onto each oneOf member whose type can carry the values.
+        # Skip Procs/Ranges to mirror build_enum_schema behavior.
+        def apply_union_enum!(members)
+          values = options[:values]
+          return if values.nil? || values.is_a?(Proc) || values.is_a?(Range)
+
+          members.each do |member|
+            case member[:type]
+            when 'integer'
+              ints = values.select { |v| v.is_a?(Integer) }
+              member[:enum] = ints if ints.any?
+            when 'number'
+              nums = values.select { |v| v.is_a?(Numeric) }
+              member[:enum] = nums if nums.any?
+            when 'string'
+              member[:enum] = values.map(&:to_s)
+            end
+          end
+        end
+
+        # When a union (oneOf) schema has a `default:`, attach it to every member
+        # whose schema can accept the default value. For arrays this includes
+        # checking the items type so `[1, 2]` lands on `items: { type: integer }`
+        # but not on `items: { type: string }`. Empty arrays are type-agnostic
+        # and attach to all array members.
+        def apply_union_default!(members)
+          default = options[:default]
+          return unless default && serializable?(default)
+
+          members.each do |member|
+            member[:default] = default if member_accepts_default?(member, default)
+          end
+        end
+
+        def member_accepts_default?(member, default)
+          case member[:type]
+          when 'integer' then default.is_a?(Integer)
+          when 'number'  then default.is_a?(Numeric)
+          when 'boolean' then [true, false].include?(default)
+          when 'string'  then default.is_a?(String) || default.is_a?(Symbol)
+          when 'array'   then array_member_accepts?(member, default)
+          when 'object'  then default.is_a?(Hash)
+          end
+        end
+
+        def array_member_accepts?(member, default)
+          return false unless default.is_a?(Array)
+          return true if default.empty?
+
+          item_type = member.dig(:items, :type)
+          default.all? { |element| openapi_type_accepts?(item_type, element) }
+        end
+
+        def openapi_type_accepts?(openapi_type, value)
+          case openapi_type
+          when 'integer' then value.is_a?(Integer)
+          when 'number'  then value.is_a?(Numeric)
+          when 'boolean' then [true, false].include?(value)
+          when 'string'  then value.is_a?(String) || value.is_a?(Symbol)
+          else true
+          end
+        end
+
+        # allow_blank defaults to true
+        # when `allow_blank: false` for a string type minLength should be set to 1
+        # when param is required and values option used, the param is not nullable
+        def apply_allow_blank(schema)
+          if options[:allow_blank] == false || (options[:required] && options[:values])
+            schema[:minLength] = 1 if schema[:type] == 'string'
+          elsif in_value != 'path'
+            # path parameters are never nullable because they are required URL segments
+            if schema[:oneOf]
+              schema[:oneOf].each { |s| s[:nullable] = true }
+            else
+              schema[:nullable] = true
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class PathConverter
+        # Grape stores response-entity declarations under :entity (when declared
+        # via `entity:` on the route) and :success (when declared via the `success`
+        # DSL inside a `desc` block, in any of its forms). EntityConverter.register
+        # handles all three shapes (Class, Hash with :model, Array of those).
+        RESPONSE_DECLARATIONS = %i[entity success].freeze
+
+        def self.convert(routes, schema_registry, request_body_registry)
+          new(routes, schema_registry, request_body_registry).convert
+        end
+
+        def initialize(routes, schema_registry, request_body_registry)
+          @routes = routes
+          @schema_registry = schema_registry
+          @request_body_registry = request_body_registry
+          @config = Gitlab::GrapeOpenapi.configuration
+          @inherited_path_params = {}
+        end
+
+        def convert
+          register_inherited_path_params
+
+          paths = grouped_routes.transform_values do |routes_for_path|
+            build_path_item(routes_for_path)
+          end
+
+          paths.reject { |_path, operations| operations.empty? }
+        end
+
+        private
+
+        attr_reader :config, :routes, :schema_registry, :request_body_registry, :inherited_path_params
+
+        def grouped_routes
+          groups = {}
+
+          routes.each do |route|
+            next if skip_route?(route)
+
+            register_route_entities(route)
+
+            key = grouping_key(route)
+            groups[key] ||= []
+            groups[key] << route
+          end
+
+          groups.transform_keys { |key| normalize_path(groups[key].first) }
+        end
+
+        # Register entities declared on the route's response so they appear in
+        # `components.schemas` only for routes that are actually emitted.
+        # Running this after `skip_route?` keeps registration in sync with the
+        # final spec and avoids `no-unused-components` orphans for entities
+        # that belong only to hidden routes or wildcard catch-alls.
+        def register_route_entities(route)
+          RESPONSE_DECLARATIONS.each do |key|
+            definition = route.options[key]
+            next unless definition
+
+            EntityConverter.register(definition, @schema_registry)
+          end
+        end
+
+        def skip_route?(route)
+          method = extract_method(route)
+          path = normalize_path(route)
+
+          # Hidden routes (declared with `hidden true`) must be skipped before
+          # OperationConverter runs. Otherwise it pollutes the shared schema and
+          # request-body registries with entries that no emitted operation references,
+          # surfacing as `no-unused-components` warnings under `components.schemas`.
+          return true if hidden?(route)
+
+          # Grape registers catch-all routes with HTTP method * (matches any method) and
+          # paths containing *path (wildcard segments). Neither is valid OpenAPI: * isn't
+          # an HTTP method, and *path isn't a valid path segment. These are internal
+          # Grape routing artifacts, not actual API endpoints.
+          method == '*' || path.include?('*')
+        end
+
+        def hidden?(route)
+          !!route.options.dig(:settings, :description, :hidden)
+        end
+
+        def normalize_path(route)
+          path = route.pattern.origin
+
+          path
+            .gsub(/\(\.:format\)$/, '')
+            .gsub(/:\w+/) { |match| "{#{match[1..]}}" }
+            .gsub('{version}', config.api_version)
+        end
+
+        def grouping_key(route)
+          normalize_path(route).gsub(/\{[^}]+\}/, '{param}')
+        end
+
+        def build_path_item(routes_for_path)
+          path_item = Models::PathItem.new
+
+          routes_for_path.each do |route|
+            operation = OperationConverter.convert(
+              route,
+              schema_registry,
+              request_body_registry,
+              inherited_path_params: inherited_path_params
+            )
+            method = extract_method(route)
+            path_item.add_operation(method, operation)
+          end
+
+          path_item.to_h
+        end
+
+        def extract_method(route)
+          route.request_method
+        end
+
+        # Index every declared path placeholder by the path prefix that
+        # introduces it, so a route that does not declare a placeholder
+        # itself can still inherit the declaration from a sibling route
+        # (e.g. a mounted child route inheriting `:id` from its mount
+        # parent, where Grape drops the parent's `requires :id` from the
+        # child route's own `options[:params]`).
+        def register_inherited_path_params
+          routes.each do |route|
+            next if skip_route?(route)
+
+            declared = route.options[:params] || {}
+            next if declared.empty?
+
+            segments = normalize_path(route).split('/')
+
+            declared.each do |placeholder_name, param_options|
+              placeholder_pattern = "{#{placeholder_name}}"
+              idx = segments.index(placeholder_pattern)
+              next unless idx
+
+              prefix = segments[0..idx].join('/')
+              inherited_path_params[[prefix, placeholder_name]] ||= param_options
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class RequestBodyConverter
+        DEFAULT_CONTENT_TYPE = 'application/json'
+        MULTIPART_FORM_DATA_CONTENT_TYPE = 'multipart/form-data'
+        GET_METHOD = 'GET'
+        DELETE_METHOD = 'DELETE'
+
+        attr_reader :route, :options, :params, :request_body_registry
+
+        def self.convert(route:, options:, params:, request_body_registry:)
+          new(route: route, options: options, params: params, request_body_registry: request_body_registry).convert
+        end
+
+        def initialize(route:, options:, params:, request_body_registry:)
+          @route = route
+          @options = options
+          @params = params
+          @request_body_registry = request_body_registry
+        end
+
+        def convert
+          return nil if route_method == GET_METHOD || route_method == DELETE_METHOD
+          return nil if params.empty?
+
+          body_params = Models::RequestBody::Parameters.new(route: route, params: params).extract
+          return nil if body_params.empty?
+
+          build_request_body(body_params)
+        end
+
+        private
+
+        def route_method
+          route.request_method
+        end
+
+        def build_request_body(body_params)
+          properties = {}
+          required_params = []
+
+          body_params.each do |key, param_options|
+            schema = Models::RequestBody::ParameterSchema.new(
+              route: route, key: key, param_options: param_options
+            ).build
+            properties[key.to_s] = schema
+            required_params << key.to_s if param_options[:required]
+          end
+
+          schema = {
+            type: 'object',
+            properties: properties
+          }
+          schema[:required] = required_params unless required_params.empty?
+
+          schema_ref = request_body_registry.register(schema)
+
+          {
+            required: required_params.any?,
+            content: {
+              content_type(body_params) => {
+                schema: schema_ref
+              }
+            }
+          }
+        end
+
+        def content_type(body_params)
+          custom_content_type = extract_consumes_content_type
+          return custom_content_type if custom_content_type
+
+          return MULTIPART_FORM_DATA_CONTENT_TYPE if allows_file_upload?(body_params)
+
+          DEFAULT_CONTENT_TYPE
+        end
+
+        def extract_consumes_content_type
+          consumes = route.settings.dig(:description, :consumes)
+          return nil if consumes.blank?
+
+          content_type = consumes.first
+          content_type = DEFAULT_CONTENT_TYPE if content_type == :json
+          content_type
+        end
+
+        def allows_file_upload?(body_params)
+          body_params.any? do |_key, param_options|
+            param_options[:type]&.include?('API::Validations::Types::WorkhorseFile')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class ResponseConverter
+        def initialize(route, schema_registry)
+          @route = route
+          @schema_registry = schema_registry
+          @responses = {}
+        end
+
+        def convert
+          extract_success_response
+          extract_failure_responses
+          @responses
+        end
+
+        private
+
+        def extract_success_response
+          entity_definition = @route.options[:entity] || @route.options[:success]
+
+          case entity_definition
+          when nil
+            success_code = infer_success_code
+            add_simple_response(
+              status_code: success_code,
+              description: http_status_text(success_code)
+            )
+          when Class
+            process_class_entity(entity_definition)
+          when Hash
+            process_hash_entity(entity_definition)
+          when Array
+            process_array_entities(entity_definition)
+          end
+        end
+
+        def process_class_entity(entity_class)
+          success_code = infer_success_code
+          if EntityConverter.grape_entity?(entity_class)
+            add_response_with_entity(
+              status_code: success_code,
+              description: http_status_text(success_code),
+              entity_class: entity_class
+            )
+          else
+            add_simple_response(
+              status_code: success_code,
+              description: http_status_text(success_code)
+            )
+          end
+        end
+
+        def process_hash_entity(entity_hash)
+          success_code = infer_success_code
+
+          if entity_hash[:model] && EntityConverter.grape_entity?(entity_hash[:model])
+            add_response_with_entity(
+              status_code: entity_hash[:code] || success_code,
+              description: entity_hash[:message] || http_status_text(entity_hash[:code] || success_code),
+              entity_class: entity_hash[:model],
+              example: entity_hash[:example],
+              examples: entity_hash[:examples]
+            )
+          else
+            add_simple_response(
+              status_code: entity_hash[:code] || success_code,
+              description: entity_hash[:message] || http_status_text(entity_hash[:code] || success_code)
+            )
+          end
+        end
+
+        def process_array_entities(entity_array)
+          entity_array.each do |definition|
+            case definition
+            when Hash
+              process_array_hash_item(definition)
+            when Class
+              process_class_entity(definition)
+            end
+          end
+        end
+
+        def process_array_hash_item(definition)
+          if definition[:model] && EntityConverter.grape_entity?(definition[:model])
+            add_response_with_entity(
+              status_code: definition[:code] || infer_success_code,
+              description: definition[:message] || http_status_text(definition[:code] || infer_success_code),
+              entity_class: definition[:model],
+              example: definition[:example],
+              examples: definition[:examples]
+            )
+          else
+            add_simple_response(
+              status_code: definition[:code] || infer_success_code,
+              description: definition[:message] || http_status_text(definition[:code] || infer_success_code)
+            )
+          end
+        end
+
+        def extract_failure_responses
+          http_codes = @route.http_codes.presence || infer_failure_codes
+
+          http_codes.each do |failure_def|
+            case failure_def
+            when Hash
+              add_simple_response(
+                status_code: failure_def[:code],
+                description: failure_def[:message] || http_status_text(failure_def[:code])
+              )
+            when Array
+              add_simple_response(
+                status_code: failure_def[0],
+                description: failure_def[1] || http_status_text(failure_def[0])
+              )
+            end
+          end
+        end
+
+        def add_response_with_entity(status_code:, description:, entity_class:, example: nil, examples: nil)
+          response = Models::Response.new(
+            status_code: status_code,
+            description: description,
+            entity_class: entity_class,
+            example: example,
+            examples: examples
+          )
+
+          @responses[response.status_code] = response.to_h(@schema_registry)
+        end
+
+        def add_simple_response(status_code:, description:)
+          key = status_code.to_s
+
+          # `http_codes` (processed by `extract_failure_responses`) may include
+          # success codes that are also covered by a `success`/`entity`
+          # declaration. Preserve the existing response content (the entity
+          # `$ref`) and only refresh the description, so the entity is not
+          # silently dropped.
+          if @responses[key]
+            @responses[key][:description] = description
+          else
+            @responses[key] = { description: description }
+          end
+        end
+
+        def infer_success_code
+          case http_method
+          when 'POST' then 201
+          when 'DELETE' then 204
+          else 200
+          end
+        end
+
+        def infer_failure_codes
+          codes = []
+          codes << 404 if path_has_resource_parameters?
+          codes << 400 if route_params.any? || %w[POST PUT PATCH].include?(http_method)
+          codes.map { |code| { code: code, message: http_status_text(code) } }
+        end
+
+        def route_params
+          @route.options[:params] || {}
+        end
+
+        def path_has_resource_parameters?
+          path = @route.path
+            .gsub('.:format', '')
+            .gsub(':version', '')
+          path.include?(':')
+        end
+
+        def http_status_text(code)
+          Rack::Utils::HTTP_STATUS_CODES[code.to_i] || 'Success'
+        end
+
+        def http_method
+          @route.request_method
+        end
+      end
+    end
+  end
+end