gitlab-grape-openapi 0.0.0 → 0.1.0

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#response-object
+      class Response
+        attr_reader :status_code, :description, :entity_class, :headers, :content_type
+
+        def initialize(
+          status_code:, description:, entity_class:, headers: {}, content_type: 'application/json',
+          example: nil, examples: nil)
+          @status_code = status_code.to_s
+          @description = description
+          @entity_class = entity_class
+          @headers = headers
+          @content_type = content_type
+          @example = example
+          @examples = examples
+        end
+
+        def to_h(schema_registry)
+          response = {
+            description: description,
+            content: {
+              content_type => {
+                schema: { '$ref' => schema_ref(schema_registry) },
+                example: @example,
+                examples: @examples
+              }.compact
+            }
+          }
+
+          response[:headers] = headers if headers.any?
+
+          response
+        end
+
+        private
+
+        def schema_ref(schema_registry)
+          normalized_name = schema_registry.register(entity_class, nil)
+          "#/components/schemas/#{normalized_name}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schema-object
+      class Schema
+        attr_accessor :properties, :type
+
+        def initialize
+          @properties = {}
+        end
+
+        def method_missing(method_name, *_args)
+          raise NoMethodError unless respond_to_missing?(method_name)
+
+          properties[method_name]
+        end
+
+        def respond_to_missing?(method_name, _include_private = false)
+          properties.key?(method_name)
+        end
+
+        def to_h
+          build_schema_hash
+        end
+
+        private
+
+        def build_schema_hash
+          {}.tap do |hash|
+            add_type(hash)
+            add_properties(hash)
+          end
+        end
+
+        def add_type(hash)
+          hash[:type] = type if type
+        end
+
+        def add_properties(hash)
+          return if properties.empty?
+
+          hash[:properties] = properties.transform_values(&:to_h)
+        end
+
+        def description
+          @properties[:description]
+        end
+
+        def default
+          @properties[:default]
+        end
+
+        def example
+          @properties[:example]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#security-scheme-object
+      class SecurityScheme
+        VALID_TYPES = %w[apiKey http oauth2 openIdConnect].freeze
+        VALID_IN_VALUES = %w[query header cookie].freeze
+        VALID_HTTP_SCHEMES = %w[basic bearer oauth].freeze
+
+        attr_accessor :type, :description, :name, :in, :scheme, :bearer_format,
+          :flows, :open_id_connect_url
+
+        def initialize(type:, **options)
+          @type = type
+          validate_type!
+
+          @description = options[:description]
+
+          case @type
+          when 'apiKey'
+            @name = options[:name] || raise(ArgumentError, "name is required for apiKey type")
+            @in = options[:in] || raise(ArgumentError, "in is required for apiKey type")
+            validate_in!
+          when 'http'
+            @scheme = options[:scheme] || raise(ArgumentError, "scheme is required for http type")
+            validate_http_scheme!
+            @bearer_format = options[:bearer_format] if @scheme == 'bearer'
+          when 'oauth2'
+            @flows = options[:flows] || raise(ArgumentError, "flows is required for oauth2 type")
+            validate_oauth2_flows!
+          when 'openIdConnect'
+            @open_id_connect_url = options[:open_id_connect_url] ||
+              raise(ArgumentError, "open_id_connect_url is required for openIdConnect type")
+          end
+        end
+
+        def to_h
+          hash = { 'type' => @type }
+          hash['description'] = @description if @description
+
+          case @type
+          when 'apiKey'
+            hash['name'] = @name
+            hash['in'] = @in
+          when 'http'
+            hash['scheme'] = @scheme
+            hash['bearerFormat'] = @bearer_format if @bearer_format
+          when 'oauth2'
+            hash['flows'] = flows_to_hash(@flows)
+          when 'openIdConnect'
+            hash['openIdConnectUrl'] = @open_id_connect_url
+          end
+
+          hash
+        end
+
+        private
+
+        def validate_type!
+          return if VALID_TYPES.include?(@type)
+
+          raise ArgumentError, "Invalid type: #{@type}. Must be one of: #{VALID_TYPES.join(', ')}"
+        end
+
+        def validate_in!
+          return if VALID_IN_VALUES.include?(@in)
+
+          raise ArgumentError, "Invalid 'in' value: #{@in}. Must be one of: #{VALID_IN_VALUES.join(', ')}"
+        end
+
+        def validate_http_scheme!
+          return if VALID_HTTP_SCHEMES.include?(@scheme.downcase)
+
+          raise ArgumentError, "Invalid HTTP scheme: #{@scheme}. Common values: #{VALID_HTTP_SCHEMES.join(', ')}"
+        end
+
+        def validate_oauth2_flows!
+          raise ArgumentError, "flows must be a Hash" unless @flows.is_a?(Hash)
+
+          valid_flow_types = %w[implicit password clientCredentials authorizationCode]
+          @flows.each do |flow_type, flow_config|
+            unless valid_flow_types.include?(flow_type.to_s)
+              raise ArgumentError, "Invalid flow type: #{flow_type}. Must be one of: #{valid_flow_types.join(', ')}"
+            end
+
+            validate_flow_config!(flow_type.to_s, flow_config)
+          end
+        end
+
+        # rubocop:disable Metrics/CyclomaticComplexity -- Method is clear and readable
+        def validate_flow_config!(flow_type, config)
+          raise ArgumentError, "Flow configuration must be a Hash" unless config.is_a?(Hash)
+
+          case flow_type
+          when 'implicit'
+            raise ArgumentError, "authorizationUrl required for implicit flow" unless config[:authorizationUrl]
+            raise ArgumentError, "scopes required for implicit flow" unless config[:scopes]
+          when 'password'
+            raise ArgumentError, "tokenUrl required for password flow" unless config[:tokenUrl]
+            raise ArgumentError, "scopes required for password flow" unless config[:scopes]
+          when 'clientCredentials'
+            raise ArgumentError, "tokenUrl required for clientCredentials flow" unless config[:tokenUrl]
+            raise ArgumentError, "scopes required for clientCredentials flow" unless config[:scopes]
+          when 'authorizationCode'
+            raise ArgumentError, "authorizationUrl required for authorizationCode flow" unless config[:authorizationUrl]
+            raise ArgumentError, "tokenUrl required for authorizationCode flow" unless config[:tokenUrl]
+            raise ArgumentError, "scopes required for authorizationCode flow" unless config[:scopes]
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity
+
+        def flows_to_hash(flows)
+          result = {}
+          flows.each do |flow_type, config|
+            flow_hash = {}
+            flow_hash['authorizationUrl'] = config[:authorizationUrl] if config[:authorizationUrl]
+            flow_hash['tokenUrl'] = config[:tokenUrl] if config[:tokenUrl]
+            flow_hash['refreshUrl'] = config[:refreshUrl] if config[:refreshUrl]
+            scopes = config[:scopes]
+            flow_hash['scopes'] = scopes.respond_to?(:call) ? scopes.call : (scopes || {})
+            result[flow_type.to_s] = flow_hash
+          end
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object
+      class Server
+        attr_reader :url, :description, :variables
+
+        def initialize(url:, description: nil, variables: nil)
+          @url = url
+          @description = description
+          @variables = variables
+        end
+
+        def to_h
+          hash = { url: url }
+          hash[:description] = description if description.present?
+          hash[:variables] = variables_to_h if variables.present?
+          hash
+        end
+
+        private
+
+        def variables_to_h
+          variables.transform_values(&:to_h)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-variable-object
+      class ServerVariable
+        attr_reader :default, :description, :enum
+
+        def initialize(default:, description: nil, enum: nil)
+          @default = default
+          @description = description
+          @enum = enum
+        end
+
+        def to_h
+          hash = { default: default }
+          hash[:description] = description if description.present?
+          hash[:enum] = enum if enum.present?
+          hash
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Models
+      class Tag
+        def self.normalize_tag_name(tag_name)
+          name = tag_name.split('_').join(' ').capitalize
+          apply_overrides(name)
+        end
+
+        def self.apply_overrides(text)
+          overrides = Gitlab::GrapeOpenapi.configuration.tag_overrides
+
+          return text if overrides.nil? || overrides.empty?
+
+          pattern = Regexp.union(overrides.keys.map { |key| /\b#{Regexp.escape(key)}\b/i })
+          text.gsub(pattern) do |match|
+            overrides[match] || overrides[match.downcase] || overrides[match.capitalize] || match
+          end
+        end
+
+        attr_reader :name
+
+        def initialize(name)
+          @name = Gitlab::GrapeOpenapi::Models::Tag.normalize_tag_name(name)
+        end
+
+        def to_h
+          {
+            name: name,
+            description: description
+          }.compact
+        end
+
+        def description
+          desc_name = name.downcase
+          desc_adjusted = self.class.apply_overrides(desc_name)
+          "Operations related to #{desc_adjusted}."
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/request_body_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Gitlab
+  module GrapeOpenapi
+    class RequestBodyRegistry
+      SCHEMA_PATH_PREFIX = '#/components/schemas/'
+
+      attr_reader :schemas
+
+      def initialize
+        @schemas = {}
+        @schema_hashes = {}
+      end
+
+      def register(schema)
+        return nil if schema.blank?
+
+        schema_hash = compute_hash(schema)
+
+        if @schema_hashes.key?(schema_hash)
+          existing_name = @schema_hashes[schema_hash]
+          return { '$ref' => "#{SCHEMA_PATH_PREFIX}#{existing_name}" }
+        end
+
+        name = "RequestBody_#{short_hash(schema_hash)}"
+        @schemas[name] = schema
+        @schema_hashes[schema_hash] = name
+
+        { '$ref' => "#{SCHEMA_PATH_PREFIX}#{name}" }
+      end
+
+      private
+
+      def compute_hash(schema)
+        normalized = normalize_for_hash(schema)
+        OpenSSL::Digest::SHA256.hexdigest(normalized.to_s)
+      end
+
+      def short_hash(full_hash)
+        full_hash[0, 12]
+      end
+
+      def normalize_for_hash(obj)
+        case obj
+        when Hash
+          obj.sort.map { |k, v| [k.to_s, normalize_for_hash(v)] }
+        when Array
+          obj.map { |v| normalize_for_hash(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/schema_registry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    class SchemaRegistry
+      attr_reader :schemas
+
+      def initialize
+        @schemas = {}
+      end
+
+      def register(entity_class, schema)
+        normalized_name = normalize_entity_class(entity_class)
+        return normalized_name if @schemas.key?(normalized_name)
+        return normalized_name unless schema.is_a?(Models::Schema)
+
+        @schemas[normalized_name] = schema
+        normalized_name
+      end
+
+      def normalize_entity_class(entity_class)
+        entity_class.name.delete(':')
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/serializers/time.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Serializers
+      class Time
+        DEFAULT_TIME = '2025-08-01T00:00:00.000Z'
+
+        def serialize(value, example: nil)
+          return unless defined?(ActiveSupport::TimeWithZone) && value.is_a?(ActiveSupport::TimeWithZone)
+
+          return example if example
+
+          DEFAULT_TIME
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/tag_registry.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    class TagRegistry
+      attr_reader :tags
+
+      def initialize
+        @tags = []
+      end
+
+      def register(tag)
+        return if tag_exists?(tag)
+
+        tags << tag.to_h
+      end
+
+      def to_h
+        { tags: @tags }
+      end
+
+      private
+
+      def tag_exists?(tag)
+        tags.any? { |existing_tag| existing_tag[:name] == tag.name }
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    # Version of the gem
+    VERSION = "0.1.0"
+  end
+end

data/lib/gitlab-grape-openapi.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "gitlab/grape_openapi/version"
+require_relative "gitlab/grape_openapi/configuration"
+require_relative "gitlab/grape_openapi/generator"
+require_relative "gitlab/grape_openapi/schema_registry"
+require_relative "gitlab/grape_openapi/request_body_registry"
+require_relative "gitlab/grape_openapi/tag_registry"
+
+# Concerns
+require_relative "gitlab/grape_openapi/concerns/serializable"
+require_relative "gitlab/grape_openapi/concerns/limit_resolver"
+require_relative "gitlab/grape_openapi/concerns/fail_fast_annotatable"
+require_relative "gitlab/grape_openapi/concerns/regex_converter"
+
+# Serializers
+require_relative "gitlab/grape_openapi/serializers/time"
+
+# Converters
+require_relative "gitlab/grape_openapi/converters/coercer_resolver"
+require_relative "gitlab/grape_openapi/converters/entity_converter"
+require_relative "gitlab/grape_openapi/converters/type_resolver"
+require_relative "gitlab/grape_openapi/converters/tag_converter"
+require_relative "gitlab/grape_openapi/converters/operation_converter"
+require_relative "gitlab/grape_openapi/converters/path_converter"
+require_relative "gitlab/grape_openapi/converters/parameter_converter"
+require_relative "gitlab/grape_openapi/converters/response_converter"
+require_relative "gitlab/grape_openapi/converters/request_body_converter"
+
+# Models
+require_relative "gitlab/grape_openapi/models/request_body/parameter_schema"
+require_relative "gitlab/grape_openapi/models/request_body/parameters"
+require_relative "gitlab/grape_openapi/models/schema"
+require_relative "gitlab/grape_openapi/models/tag"
+require_relative "gitlab/grape_openapi/models/server_variable"
+require_relative "gitlab/grape_openapi/models/server"
+require_relative "gitlab/grape_openapi/models/operation"
+require_relative "gitlab/grape_openapi/models/path_item"
+require_relative "gitlab/grape_openapi/models/response"
+require_relative "gitlab/grape_openapi/models/security_scheme"
+require_relative "gitlab/grape_openapi/models/info"
+require_relative "gitlab/grape_openapi/models/parameter"
+
+module Gitlab
+  module GrapeOpenapi
+    GenerationError = Class.new(StandardError)
+
+    class << self
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def generate(options = {})
+        Generator.new(options).generate
+      end
+    end
+  end
+end