rapitapir 0.1.0

data/lib/rapitapir/dsl/fluent_endpoint_builder.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require_relative '../types'
+require_relative '../schema'
+require_relative '../core/enhanced_endpoint'
+require_relative 'enhanced_structures'
+
+module RapiTapir
+  module DSL
+    # Fluent builder for creating endpoints with a chainable DSL
+    class FluentEndpointBuilder
+      attr_reader :method, :path, :inputs, :outputs, :errors, :metadata, :security_schemes
+
+      def initialize(method, path)
+        @method = method.to_sym
+        @path = path.to_s
+        @inputs = []
+        @outputs = []
+        @errors = []
+        @metadata = {}
+        @security_schemes = []
+        @scopes = []
+      end
+
+      # Create a copy of this builder with new data
+      def copy_with(**changes)
+        new_builder = self.class.new(@method, @path)
+        copy_instance_variables_to_builder(new_builder, changes)
+        new_builder
+      end
+
+      private
+
+      def copy_instance_variables_to_builder(new_builder, changes)
+        copy_inputs_to_builder(new_builder, changes)
+        copy_outputs_and_errors_to_builder(new_builder, changes)
+        copy_metadata_and_security_to_builder(new_builder, changes)
+      end
+
+      def copy_inputs_to_builder(new_builder, changes)
+        new_builder.instance_variable_set(:@inputs, changes[:inputs] || @inputs.dup)
+      end
+
+      def copy_outputs_and_errors_to_builder(new_builder, changes)
+        new_builder.instance_variable_set(:@outputs, changes[:outputs] || @outputs.dup)
+        new_builder.instance_variable_set(:@errors, changes[:errors] || @errors.dup)
+      end
+
+      def copy_metadata_and_security_to_builder(new_builder, changes)
+        new_builder.instance_variable_set(:@metadata, changes[:metadata] || @metadata.dup)
+        new_builder.instance_variable_set(:@security_schemes, changes[:security_schemes] || @security_schemes.dup)
+        new_builder.instance_variable_set(:@scopes, changes[:scopes] || @scopes.dup)
+      end
+
+      public
+
+      # Documentation methods
+      def summary(text)
+        copy_with(metadata: @metadata.merge(summary: text))
+      end
+
+      def description(text)
+        copy_with(metadata: @metadata.merge(description: text))
+      end
+
+      def tags(*tag_list)
+        copy_with(metadata: @metadata.merge(tags: tag_list.flatten))
+      end
+
+      # Input specification methods
+      def query(name, type_def, **options)
+        type = resolve_type(type_def)
+        input = create_input(:query, name, type, **options)
+        copy_with(inputs: @inputs + [input])
+      end
+
+      def path_param(name, type_def, **options)
+        type = resolve_type(type_def)
+        input = create_input(:path, name, type, **options)
+        copy_with(inputs: @inputs + [input])
+      end
+
+      def header(name, type_def, **options)
+        type = resolve_type(type_def)
+        input = create_input(:header, name, type, **options)
+        copy_with(inputs: @inputs + [input])
+      end
+
+      def json_body(type_def, **options)
+        type = resolve_type(type_def)
+        input = create_input(:body, :body, type, format: :json, **options)
+        copy_with(inputs: @inputs + [input])
+      end
+
+      def form_body(type_def, **options)
+        type = resolve_type(type_def)
+        input = create_input(:body, :body, type, format: :form, **options)
+        copy_with(inputs: @inputs + [input])
+      end
+
+      def body(type_def, content_type: 'application/json', **options)
+        type = resolve_type(type_def)
+        input = create_input(:body, :body, type, content_type: content_type, **options)
+        copy_with(inputs: @inputs + [input])
+      end
+
+      # Output specification methods
+      def responds_with(status_code, **options)
+        output = create_output(status_code, **options)
+        copy_with(outputs: @outputs + [output])
+      end
+
+      def json_response(status_code, type_def, **options)
+        type = resolve_type(type_def)
+        output = create_output(status_code, type: type, content_type: 'application/json', **options)
+        copy_with(outputs: @outputs + [output])
+      end
+
+      def text_response(status_code, type_def = Types.string, **options)
+        type = resolve_type(type_def)
+        output = create_output(status_code, type: type, content_type: 'text/plain', **options)
+        copy_with(outputs: @outputs + [output])
+      end
+
+      def status_response(status_code, **options)
+        output = create_output(status_code, type: nil, **options)
+        copy_with(outputs: @outputs + [output])
+      end
+
+      # Convenience methods for common status codes
+      def ok(type_def = nil, **options)
+        if type_def
+          json_response(200, type_def, **options)
+        else
+          status_response(200, **options)
+        end
+      end
+
+      def created(type_def = nil, **options)
+        if type_def
+          json_response(201, type_def, **options)
+        else
+          status_response(201, **options)
+        end
+      end
+
+      def accepted(**options)
+        status_response(202, **options)
+      end
+
+      def no_content(**options)
+        status_response(204, **options)
+      end
+
+      # Error response methods
+      def error_response(status_code, type_def = nil, **options)
+        type = type_def ? resolve_type(type_def) : nil
+        error = create_error(status_code, type, **options)
+        copy_with(errors: @errors + [error])
+      end
+
+      def bad_request(type_def = nil, **options)
+        error_response(400, type_def, **options)
+      end
+
+      def unauthorized(type_def = nil, **options)
+        error_response(401, type_def, **options)
+      end
+
+      def forbidden(type_def = nil, **options)
+        error_response(403, type_def, **options)
+      end
+
+      def not_found(type_def = nil, **options)
+        error_response(404, type_def, **options)
+      end
+
+      def unprocessable_entity(type_def = nil, **options)
+        error_response(422, type_def, **options)
+      end
+
+      def internal_server_error(type_def = nil, **options)
+        error_response(500, type_def, **options)
+      end
+
+      # Authentication methods
+      def bearer_auth(description = 'Bearer token authentication', **options)
+        security = create_security(:bearer, description, **options)
+        copy_with(security_schemes: @security_schemes + [security])
+      end
+
+      def api_key_auth(name, location = :header, description = 'API key authentication', **options)
+        security = create_security(:api_key, description, name: name, location: location, **options)
+        copy_with(security_schemes: @security_schemes + [security])
+      end
+
+      def basic_auth(description = 'Basic authentication', **options)
+        security = create_security(:basic, description, **options)
+        copy_with(security_schemes: @security_schemes + [security])
+      end
+
+      def oauth2_auth(scopes = [], description = 'OAuth2 authentication', **options)
+        security = create_security(:oauth2, description, scopes: scopes, **options)
+        copy_with(security_schemes: @security_schemes + [security])
+      end
+
+      def requires_scope(*scope_list)
+        copy_with(scopes: @scopes + scope_list.flatten)
+      end
+
+      def optional_auth
+        copy_with(metadata: @metadata.merge(optional_auth: true))
+      end
+
+      # Build the final endpoint
+      def build
+        endpoint = Core::EnhancedEndpoint.new(
+          method: @method,
+          path: @path,
+          inputs: @inputs,
+          outputs: @outputs,
+          errors: @errors,
+          metadata: @metadata.merge(
+            security_schemes: @security_schemes,
+            scopes: @scopes
+          )
+        )
+
+        # Register the endpoint with RapiTapir
+        RapiTapir.register_endpoint(endpoint)
+        endpoint
+      end
+
+      private
+
+      def resolve_type(type_def)
+        case type_def
+        when Types::Base
+          type_def
+        when Symbol
+          resolve_symbol_type(type_def)
+        when Class
+          resolve_class_type(type_def)
+        when Schema, ->(obj) { obj.respond_to?(:validate) } # rubocop:disable Lint/DuplicateBranch
+          # Handle Schema objects and any object that can validate
+          type_def
+        else
+          raise ArgumentError, "Invalid type definition: #{type_def}"
+        end
+      end
+
+      def resolve_symbol_type(type_symbol)
+        symbol_type_mapping = {
+          string: Types.string,
+          integer: Types.integer,
+          float: Types.float,
+          boolean: Types.boolean,
+          date: Types.date,
+          datetime: Types.datetime,
+          uuid: Types.uuid,
+          email: Types.email
+        }
+
+        symbol_type_mapping[type_symbol] ||
+          raise(ArgumentError, "Unknown type symbol: #{type_symbol}")
+      end
+
+      def resolve_class_type(type_class)
+        raise ArgumentError, 'Type class must inherit from Types::Base' unless type_class < Types::Base
+
+        type_class.new
+      end
+
+      def create_input(kind, name, type, **options)
+        DSL::EnhancedInput.new(
+          kind: kind,
+          name: name,
+          type: type,
+          required: options.fetch(:required, true),
+          description: options[:description],
+          example: options[:example],
+          format: options[:format],
+          content_type: options[:content_type]
+        )
+      end
+
+      def create_output(status_code, **options)
+        DSL::EnhancedOutput.new(
+          status_code: status_code,
+          type: options[:type],
+          content_type: options[:content_type],
+          description: options[:description],
+          example: options[:example],
+          headers: options[:headers] || {}
+        )
+      end
+
+      def create_error(status_code, type, **options)
+        DSL::EnhancedError.new(
+          status_code: status_code,
+          type: type,
+          description: options[:description],
+          example: options[:example]
+        )
+      end
+
+      def create_security(type, description, **options)
+        DSL::EnhancedSecurity.new(
+          type: type,
+          description: description,
+          **options
+        )
+      end
+    end
+  end
+end

data/lib/rapitapir/dsl/http_verbs.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# RapiTapir Enhanced DSL Module
+# Provides concise HTTP verb methods for more readable endpoint definitions
+#
+# @example Usage
+#   include RapiTapir::DSL::HTTPVerbs
+#
+#   endpoint = GET('/users')
+#     .ok(RapiTapir::Types.array(UserSchema))
+#     .summary('Get all users')
+#     .build
+#
+#   endpoint = POST('/users')
+#     .body(UserSchema)
+#     .created(UserSchema)
+#     .summary('Create a user')
+#     .build
+
+module RapiTapir
+  module DSL
+    # HTTP Verbs mixin module
+    # Provides concise HTTP verb methods that can be included in any class
+    module HTTPVerbs
+      # HTTP GET endpoint
+      # @param path [String] The endpoint path
+      # @return [DSL::FluentEndpointBuilder] Builder for method chaining
+      # rubocop:disable Naming/MethodName
+      def GET(path)
+        RapiTapir.get(path)
+      end
+
+      # HTTP POST endpoint
+      # @param path [String] The endpoint path
+      # @return [DSL::FluentEndpointBuilder] Builder for method chaining
+      def POST(path)
+        RapiTapir.post(path)
+      end
+
+      # HTTP PUT endpoint
+      # @param path [String] The endpoint path
+      # @return [DSL::FluentEndpointBuilder] Builder for method chaining
+      def PUT(path)
+        RapiTapir.put(path)
+      end
+
+      # HTTP PATCH endpoint
+      # @param path [String] The endpoint path
+      # @return [DSL::FluentEndpointBuilder] Builder for method chaining
+      def PATCH(path)
+        RapiTapir.patch(path)
+      end
+
+      # HTTP DELETE endpoint
+      # @param path [String] The endpoint path
+      # @return [DSL::FluentEndpointBuilder] Builder for method chaining
+      def DELETE(path)
+        RapiTapir.delete(path)
+      end
+
+      # HTTP HEAD endpoint
+      # @param path [String] The endpoint path
+      # @return [DSL::FluentEndpointBuilder] Builder for method chaining
+      def HEAD(path)
+        RapiTapir.head(path)
+      end
+
+      # HTTP OPTIONS endpoint
+      # @param path [String] The endpoint path
+      # @return [DSL::FluentEndpointBuilder] Builder for method chaining
+      def OPTIONS(path)
+        RapiTapir.options(path)
+      end
+      # rubocop:enable Naming/MethodName
+    end
+  end
+end

data/lib/rapitapir/dsl/input_methods.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module DSL
+    # Input DSL methods for enhanced endpoint DSL
+    module InputMethods
+      # Input DSL methods
+      def query(name, type_def, **options)
+        type = resolve_type(type_def)
+        create_input(:query, name, type, **options)
+      end
+
+      def path_param(name, type_def, **options)
+        type = resolve_type(type_def)
+        create_input(:path, name, type, **options)
+      end
+
+      def header(name, type_def, **options)
+        type = resolve_type(type_def)
+        create_input(:header, name, type, **options)
+      end
+
+      def body(type_def, **options)
+        type = resolve_type(type_def)
+        create_input(:body, :body, type, **options)
+      end
+
+      def json_body(type_def, **options)
+        type = resolve_type(type_def)
+        create_input(:body, :body, type, format: :json, **options)
+      end
+
+      def form_body(type_def, **options)
+        type = resolve_type(type_def)
+        create_input(:body, :body, type, format: :form, **options)
+      end
+
+      private
+
+      def create_input(kind, name, type, **options)
+        @inputs ||= []
+        @inputs << EnhancedInput.new(kind: kind, name: name, type: type, options: options)
+        self
+      end
+    end
+  end
+end

data/lib/rapitapir/dsl/observability_methods.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module DSL
+    # Observability methods for enhanced endpoint DSL
+    module ObservabilityMethods
+      # Observability methods
+      def with_metrics(enabled: true, name: nil, labels: {})
+        @metrics_enabled = enabled
+        @metric_name = name || generate_metric_name
+        @metric_labels = labels
+        self
+      end
+
+      def with_tracing(enabled: true, span_name: nil, attributes: {})
+        @tracing_enabled = enabled
+        @trace_span_name = span_name || generate_span_name
+        @trace_attributes = attributes
+        self
+      end
+
+      def with_logging(enabled: true, **config)
+        @logging_enabled = enabled
+        @log_config = config
+        self
+      end
+
+      def metrics_enabled?
+        @metrics_enabled
+      end
+
+      def tracing_enabled?
+        @tracing_enabled
+      end
+
+      def logging_enabled?
+        @logging_enabled
+      end
+
+      def metric_labels
+        @metric_labels
+      end
+
+      def trace_attributes
+        @trace_attributes
+      end
+
+      def metric_name
+        @metric_name
+      end
+
+      def trace_span_name
+        @trace_span_name
+      end
+
+      def log_config
+        @log_config
+      end
+
+      private
+
+      def generate_metric_name
+        # Generate a metric name based on HTTP method and path
+        method = @method&.downcase || 'unknown'
+        path = if @path
+                 @path.gsub(%r{[/:]}, '_').gsub(/_{2,}/, '_').strip('_')
+               else
+                 'unknown'
+               end
+        "#{method}_#{path}"
+      end
+
+      def generate_span_name
+        # Generate a span name for tracing
+        method = @method&.upcase || 'UNKNOWN'
+        path = @path || '/unknown'
+        "HTTP #{method} #{path}"
+      end
+    end
+  end
+end

data/lib/rapitapir/dsl/output_methods.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module DSL
+    # Output DSL methods for enhanced endpoint DSL
+    module OutputMethods
+      # Output DSL methods
+      def out_json(type_def, **options)
+        type = resolve_type(type_def)
+        create_output(:json, type, **options)
+      end
+
+      def out_text(type_def = Types.string, **options)
+        type = resolve_type(type_def)
+        create_output(:text, type, **options)
+      end
+
+      def out_xml(type_def, **options)
+        type = resolve_type(type_def)
+        create_output(:xml, type, **options)
+      end
+
+      def status(code, **options)
+        create_output(:status, code, **options)
+      end
+
+      def error_out(status_code, type_def, **options)
+        type = resolve_type(type_def)
+        @error_outputs ||= []
+        @error_outputs << EnhancedOutput.new(kind: :json, type: type, options: options.merge(status: status_code))
+        self
+      end
+
+      private
+
+      def create_output(kind, type, **options)
+        @outputs ||= []
+        @outputs << EnhancedOutput.new(kind: kind, type: type, options: options)
+        self
+      end
+    end
+  end
+end

data/lib/rapitapir/dsl/type_resolution.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../types'
+require_relative '../schema'
+
+module RapiTapir
+  module DSL
+    # Type resolution methods for enhanced endpoint DSL
+    module TypeResolution
+      PRIMITIVE_TYPE_MAP = {
+        string: -> { Types.string },
+        integer: -> { Types.integer },
+        float: -> { Types.float },
+        boolean: -> { Types.boolean },
+        date: -> { Types.date },
+        datetime: -> { Types.datetime },
+        uuid: -> { Types.uuid },
+        email: -> { Types.email }
+      }.freeze
+
+      private
+
+      def resolve_type(type_def)
+        case type_def
+        when Symbol
+          create_primitive_type(type_def)
+        when Hash, Array
+          Schema.from_definition(type_def)
+        else
+          # For classes and already resolved types, return as-is
+          type_def
+        end
+      end
+
+      def create_primitive_type(symbol)
+        type_creator = PRIMITIVE_TYPE_MAP[symbol]
+        raise ArgumentError, "Unknown primitive type: #{symbol}" unless type_creator
+
+        type_creator.call
+      end
+    end
+  end
+end