gitlab-grape-openapi 0.0.0 → 0.1.0

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class TagConverter
+        attr_reader :api_class, :tag_registry
+
+        def initialize(api_class, tag_registry)
+          @api_class = api_class
+          @tag_registry = tag_registry
+        end
+
+        def convert
+          tags = build_tags(api_class)
+
+          tags.each do |tag|
+            tag_registry.register(tag)
+          end
+        end
+
+        private
+
+        def build_tags(api_class)
+          tags = api_class.routes.flat_map do |route|
+            route.settings.dig(:description, :tags)
+          end.compact
+
+          tags.map do |tag_name|
+            Gitlab::GrapeOpenapi::Models::Tag.new(tag_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class TypeResolver
+        TYPE_MAPPINGS = {
+          'API::Validations::Types::WorkhorseFile' => 'string',
+          'Array' => 'array',
+          'BigDecimal' => 'number',
+          'Boolean' => 'boolean',
+          'date' => 'string',
+          'Date' => 'string',
+          'date-time' => 'string',
+          'dateTime' => 'string',
+          'DateTime' => 'string',
+          'FalseClass' => 'boolean',
+          'Grape::API::Boolean' => 'boolean',
+          'Gitlab::Color' => 'string',
+          :int => 'integer',
+          'int' => 'integer',
+          Integer => 'integer',
+          'Integer' => 'integer',
+          'File' => 'string',
+          Float => 'number',
+          'Float' => 'number',
+          :hash => 'object',
+          'hash' => 'object',
+          'Hash' => 'object',
+          'JSON' => 'object',
+          'Numeric' => 'number',
+          String => 'string',
+          'String' => 'string',
+          'symbol' => 'string',
+          'Symbol' => 'string',
+          'text' => 'string',
+          'Time' => 'string',
+          'TrueClass' => 'boolean'
+        }.freeze
+
+        FORMAT_MAPPINGS = {
+          'API::Validations::Types::WorkhorseFile' => 'binary',
+          'date' => 'date',
+          'Date' => 'date',
+          'date-time' => 'date-time',
+          'dateTime' => 'date-time',
+          'DateTime' => 'date-time',
+          'File' => 'binary',
+          'Time' => 'date-time'
+        }.freeze
+
+        def self.resolve_type(type)
+          return TYPE_MAPPINGS[type] if TYPE_MAPPINGS[type]
+          return type unless type.is_a?(String)
+          return 'object' if type.delete_prefix('::').start_with?('API::')
+
+          type
+        end
+
+        def self.resolve_format(format, type)
+          format || FORMAT_MAPPINGS[type]
+        end
+
+        def self.resolve_union_member(type)
+          if type.start_with?('[') && type.end_with?(']')
+            item_type = type[1..-2]
+            { type: 'array', items: { type: resolve_type(item_type) || 'string' } }
+          else
+            { type: resolve_type(type) || 'string' }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    class Generator
+      attr_reader :tag_registry
+
+      def initialize(options = {})
+        @api_classes = Array(options[:api_classes]).reject do |api_class|
+          Gitlab::GrapeOpenapi.configuration.excluded_api_classes.include?(api_class.name)
+        end
+        @schema_registry = SchemaRegistry.new
+        @request_body_registry = RequestBodyRegistry.new
+        @tag_registry = TagRegistry.new
+      end
+
+      def generate
+        initialize_tags
+
+        {
+          openapi: '3.0.0',
+          info: Gitlab::GrapeOpenapi.configuration.info.to_h,
+          tags: tag_registry.tags.sort_by { |t| t.fetch(:name, '') },
+          servers: Gitlab::GrapeOpenapi.configuration.servers.map(&:to_h),
+          paths: paths,
+          components: {
+            securitySchemes: security_schemes,
+            schemas: schemas
+          },
+          security: security_schemes.keys.map { |s| { s => [] } }
+        }
+      end
+
+      def security_schemes
+        Gitlab::GrapeOpenapi.configuration.security_schemes.to_h do |scheme|
+          [scheme.type, scheme.to_h]
+        end
+      end
+
+      def initialize_tags
+        @api_classes.each do |api_class|
+          Converters::TagConverter.new(api_class, tag_registry).convert
+        end
+      end
+
+      def paths
+        all_routes = @api_classes.flat_map(&:routes)
+        Converters::PathConverter.convert(all_routes, @schema_registry, @request_body_registry)
+      end
+
+      private
+
+      def schemas
+        entity_schemas = @schema_registry.schemas.transform_values(&:to_h)
+        request_body_schemas = @request_body_registry.schemas
+        entity_schemas.merge(request_body_schemas)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      class Info
+        attr_accessor :title, :description, :terms_of_service, :version, :license
+
+        def initialize(**options)
+          @title = options[:title]
+          @description = options[:description]
+          @terms_of_service = options[:terms_of_service]
+          @version = options[:version]
+          @license = options[:license]
+        end
+
+        def to_h
+          {
+            title: title,
+            description: description,
+            termsOfService: terms_of_service,
+            version: version,
+            license: license
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      class Operation
+        # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-object
+        attr_accessor :operation_id, :description, :tags, :responses, :parameters, :request_body, :summary,
+          :deprecated, :hidden, :annotations
+
+        def initialize
+          @tags = []
+          @request_body = {}
+          @parameters = []
+          @deprecated = false
+          @annotations = nil
+        end
+
+        def hidden?
+          @hidden
+        end
+
+        def to_h
+          @parameters ||= []
+
+          o = {
+            operationId: operation_id,
+            summary: summary,
+            description: description,
+            tags: tags && tags.empty? ? nil : tags,
+            responses: responses
+          }.compact
+
+          o[:deprecated] = deprecated if deprecated
+          o[:parameters] = parameters.map(&:to_h) if parameters.any?
+          o[:requestBody] = request_body if request_body.keys.any?
+
+          annotations&.each do |k, v|
+            o[k] = v
+          end
+
+          o
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      class Parameter
+        # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#parameter-object
+        attr_reader :name, :required, :in_value, :description, :options, :schema, :example
+        attr_accessor :style, :explode
+
+        def initialize(name, options:, schema:, in_value:)
+          @options = options
+          @name = name
+          # From https://spec.openapis.org/oas/v3.2.0.html#common-fixed-fields: "If the parameter
+          # location is 'path', this property is REQUIRED and its value MUST be true.
+          @required = in_value == 'path' ? true : options[:required]
+          @description = options[:desc]
+          @schema = schema
+          @in_value = in_value
+          @example = options.dig(:documentation, :example)
+          @default = options.dig(:documentation, :default)
+          @style = nil
+          @explode = nil
+        end
+
+        def to_h
+          result = {
+            name: name,
+            required: required,
+            description: description,
+            schema: schema,
+            in: in_value,
+            example: example
+          }
+
+          result[:style] = style if style
+          result[:explode] = explode unless explode.nil?
+          result.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      class PathItem
+        # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#path-item-object
+        attr_reader :operations
+
+        def initialize
+          @operations = {}
+        end
+
+        def add_operation(method, operation)
+          return if operation.hidden?
+
+          @operations[method.to_s.downcase] = operation
+        end
+
+        def to_h
+          operations.transform_values(&:to_h)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      module RequestBody
+        class ParameterSchema
+          include Converters::CoercerResolver
+          include Concerns::Serializable
+          include Concerns::LimitResolver
+          include Concerns::FailFastAnnotatable
+          include Concerns::RegexConverter
+
+          def initialize(route:, key:, param_options:)
+            @route = route
+            @key = key
+            @param_options = param_options
+            @validations = validations_for(key.to_sym)
+          end
+
+          def build
+            fail_fast = fail_fast_in_validations?(validations)
+            @param_options = param_options.merge(fail_fast: fail_fast) if fail_fast
+            built_schema = build_raw_type_schema
+
+            unless built_schema
+              object_type = Converters::TypeResolver.resolve_type(param_options[:type]) || 'string'
+              object_format = Converters::TypeResolver.resolve_format(nil, param_options[:type])
+              built_schema = build_resolved_schema(object_type, object_format)
+            end
+
+            apply_allow_blank(built_schema)
+            apply_limit!(built_schema, validations)
+            built_schema
+          end
+
+          private
+
+          attr_reader :route, :key, :param_options, :validations
+
+          def annotated_description
+            return param_options[:desc] unless param_options[:fail_fast]
+
+            annotate_fail_fast(param_options[:desc])
+          end
+
+          # Handles schema building for types that cannot safely be passed through TypeResolver
+          def build_raw_type_schema
+            type_str = param_options[:type].to_s
+            mapping = coercer_mapping_for(validations)
+
+            if mapping
+              # Handle coerced types(e.g., coerce_with: option used)
+              build_coerced_schema_with_description(mapping)
+            elsif type_str.start_with?('[') && type_str.exclude?(',')
+              # Handle array types like [String] (single type in brackets)
+              build_simple_array_from_bracket_notation
+            elsif type_str.include?('API::Validations::Types::WorkhorseFile')
+              # Handle file types (e.g., API::Validations::Types::WorkhorseFile)
+              build_file_schema
+            elsif type_str.start_with?('[')
+              # Handle union types (e.g., [String, Integer])
+              build_union_type_schema
+            end
+          end
+
+          # Handles schema building for types that have been resolved through TypeResolver
+          def build_resolved_schema(object_type, object_format)
+            if param_options[:values].is_a?(Range)
+              # Handle range values
+              build_range_schema(object_type)
+            elsif param_options[:values]
+              # Handle enum/values
+              build_enum_schema(object_type)
+            elsif param_options[:type] == 'Array' && param_options[:params]
+              # Handle array types with nested params
+              build_nested_array_schema
+            elsif object_type.include?('[')
+              # Handle array types (simple, like Array[String])
+              build_array_schema
+            elsif param_options[:type] == 'Hash' && param_options[:params]
+              # Handle Hash types with nested params
+              build_nested_hash_schema
+            else
+              # Build basic schema
+              build_basic_schema(object_type, object_format)
+            end
+          end
+
+          def build_coerced_schema_with_description(mapping)
+            schema = build_coerced_schema(mapping)
+            schema[:description] = annotated_description if param_options[:desc]
+            schema
+          end
+
+          def build_simple_array_from_bracket_notation
+            # Handle types like [String] or [Integer]
+            item_type = param_options[:type].to_s.delete('[').delete(']')
+            schema = { type: 'array', items: { type: Converters::TypeResolver.resolve_type(item_type) } }
+            schema[:description] = annotated_description if param_options[:desc]
+            schema
+          end
+
+          def build_file_schema
+            schema = { type: 'string', format: 'binary' }
+            schema[:description] = annotated_description if param_options[:desc]
+            schema
+          end
+
+          def build_union_type_schema
+            types = param_options[:type][1..-2].split(", ")
+            { oneOf: types.map { |type| Converters::TypeResolver.resolve_union_member(type) } }
+          end
+
+          def build_range_schema(object_type)
+            range = param_options[:values]
+            schema = { type: object_type }
+            schema[:minimum] = range.begin if range.begin
+            schema[:maximum] = range.end if range.end
+            if param_options[:default] && serializable?(param_options[:default])
+              schema[:default] = param_options[:default]
+            end
+
+            schema[:description] = annotated_description if param_options[:desc]
+            schema
+          end
+
+          def build_enum_schema(object_type)
+            schema = { type: object_type }
+            schema[:enum] = param_options[:values] unless param_options[:values].is_a?(Proc)
+            if param_options[:default] && serializable?(param_options[:default])
+              schema[:default] = param_options[:default]
+            end
+
+            schema[:description] = annotated_description if param_options[:desc]
+            schema
+          end
+
+          def build_array_schema
+            item_type = param_options[:type].delete('[').delete(']').downcase
+            schema = { type: 'array', items: { type: Converters::TypeResolver.resolve_type(item_type) } }
+            schema[:description] = annotated_description if param_options[:desc]
+            schema
+          end
+
+          def build_nested_array_schema
+            schema = { type: 'array' }
+            schema[:description] = annotated_description if param_options[:desc]
+
+            # Build the items schema from nested params
+            nested_params = param_options[:params]
+            if nested_params && !nested_params.empty?
+              properties = {}
+              required_params = []
+
+              nested_params.each do |nested_key, nested_options|
+                properties[nested_key.to_s] = self.class.new(
+                  route: route, key: nested_key, param_options: nested_options
+                ).build
+                required_params << nested_key.to_s if nested_options[:required]
+              end
+
+              items_schema = {
+                type: 'object',
+                properties: properties
+              }
+              items_schema[:required] = required_params unless required_params.empty?
+
+              schema[:items] = items_schema
+            else
+              # If no nested params, default to object type
+              schema[:items] = { type: 'object' }
+            end
+
+            schema
+          end
+
+          def build_nested_hash_schema
+            schema = { type: 'object' }
+            schema[:description] = annotated_description if param_options[:desc]
+
+            # Build the properties schema from nested params
+            nested_params = param_options[:params]
+            if nested_params && !nested_params.empty?
+              properties = {}
+              required_params = []
+
+              nested_params.each do |nested_key, nested_options|
+                properties[nested_key.to_s] = self.class.new(
+                  route: route, key: nested_key, param_options: nested_options
+                ).build
+                required_params << nested_key.to_s if nested_options[:required]
+              end
+
+              schema[:properties] = properties
+              schema[:required] = required_params unless required_params.empty?
+            end
+
+            schema
+          end
+
+          def build_basic_schema(object_type, object_format)
+            schema = { type: object_type }
+            schema[:format] = object_format if object_format
+            if param_options[:default] && serializable?(param_options[:default])
+              schema[:default] = param_options[:default]
+            end
+
+            schema[:description] = annotated_description if param_options[:desc]
+
+            if param_options.dig(:documentation, :example)
+              schema[:example] = param_options.dig(:documentation, :example)
+            end
+
+            # Add regex validations
+            validation = validations&.find do |v|
+              v[:validator_class] == Grape::Validations::Validators::RegexpValidator
+            end
+
+            if validation
+              pattern = regexp_to_pattern(validation[:options])
+              schema[:pattern] = pattern if pattern
+            end
+
+            schema
+          end
+
+          def validations_for(attribute)
+            route
+              .app
+              .inheritable_setting
+              .namespace_stackable
+              .new_values[:validations]
+              &.select { |v| v[:attributes].include?(attribute) }
+          end
+
+          def apply_allow_blank(schema)
+            if param_options[:allow_blank] == false || (param_options[:required] && param_options[:values])
+              schema[:minLength] = 1 if schema[:type] == 'string'
+            elsif 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/models/request_body/parameters.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      module RequestBody
+        class Parameters
+          attr_reader :route, :params
+
+          def initialize(route:, params:)
+            @route = route
+            @params = params
+          end
+
+          def extract
+            body_params = params.reject do |key, _|
+              path_with_params.include?("{#{key}}")
+            end
+
+            restructure_nested_params(body_params)
+          end
+
+          private
+
+          def path_with_params
+            @path_with_params ||= route.origin
+              .gsub(/\(\.:format\)$/, '')
+              .gsub(/:\w+/) { |match| "{#{match[1..]}}" }
+          end
+
+          def restructure_nested_params(body_params)
+            # Separate root params from nested params (with bracket notation)
+            root_params = {}
+            nested_map = {}
+
+            body_params.each do |key, param_options|
+              key_str = key.to_s
+              if key_str.include?('[')
+                # Parse bracket notation like "assets[links][name]"
+                parts = parse_bracket_notation(key_str)
+                nested_map[parts] = param_options
+              else
+                root_params[key] = param_options
+              end
+            end
+
+            # Build nested structure
+            nested_map.each do |parts, param_options|
+              insert_nested_param(root_params, parts, param_options)
+            end
+
+            root_params
+          end
+
+          def parse_bracket_notation(key)
+            key.scan(/\w+/)
+          end
+
+          def insert_nested_param(root_params, parts, param_options)
+            return if parts.empty?
+
+            first = parts[0]
+            rest = parts[1..]
+
+            # Ensure the root param exists as a Hash/object
+            root_params[first] ||= { type: 'Hash', required: false }
+
+            if rest.empty?
+              # This is a direct property (e.g., just "config")
+              # Merge param_options to preserve description and other metadata
+              root_params[first] = root_params[first].merge(param_options)
+            elsif rest.length == 1
+              # This is the parent of the final property (e.g., "assets[links]")
+              root_params[first][:params] ||= {}
+              root_params[first][:params][rest[0]] = param_options
+            else
+              # Multiple levels remaining - recurse to handle arbitrary depth
+              # (e.g., "config[database][pool][max_connections]")
+              root_params[first][:params] ||= {}
+              insert_nested_param(root_params[first][:params], rest, param_options)
+            end
+          end
+        end
+      end
+    end
+  end
+end