rapitapir 0.1.2 → 2.0.0

data/lib/rapitapir/server/rails/resource_builder.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Server
+    module Rails
+      # Resource builder for creating RESTful API endpoints in Rails controllers
+      # Provides the same functionality as Sinatra::ResourceBuilder but adapted for Rails
+      class ResourceBuilder
+        attr_reader :endpoints
+
+        def initialize(controller_class, base_path, schema, **options)
+          @controller_class = controller_class
+          @base_path = base_path.chomp('/')
+          @schema = schema
+          @options = options
+          @endpoints = []
+        end
+
+        # Enable standard CRUD operations
+        # @param except [Array<Symbol>] Operations to exclude
+        # @param only [Array<Symbol>] Only include these operations
+        # @param block [Proc] Block defining the CRUD handlers
+        def crud(except: [], only: nil, **handlers, &block)
+          operations = only || %i[index show create update destroy]
+          operations -= except if except.any?
+
+          # If a block is given, evaluate it in the context of this ResourceBuilder
+          if block_given?
+            instance_eval(&block)
+          else
+            # Legacy style with handlers hash
+            operations.each do |operation|
+              send(operation, &handlers[operation]) if respond_to?(operation, true)
+            end
+          end
+        end
+
+        # List all resources (GET /resources)
+        # @param options [Hash] Endpoint options
+        # @param handler [Proc] Request handler
+        def index(**options, &handler)
+          handler ||= proc { [] }
+
+          endpoint_def = @controller_class.GET(@base_path)
+                                          .summary(options[:summary] || "List all #{resource_name}")
+                                          .description(options[:description] || "Retrieve a list of #{resource_name}")
+                                          .then { |ep| add_pagination_params(ep) }
+                                          .ok(RapiTapir::Types.array(@schema))
+                                          .build
+
+          @endpoints << [endpoint_def, handler]
+        end
+
+        # Get specific resource (GET /resources/:id)
+        # @param options [Hash] Endpoint options
+        # @param handler [Proc] Request handler
+        def show(**options, &handler)
+          handler ||= proc { {} }
+
+          endpoint_def = @controller_class.GET("#{@base_path}/:id")
+                                          .summary(options[:summary] || "Get #{resource_name}")
+                                          .description(options[:description] || "Retrieve a specific #{resource_name} by ID")
+                                          .path_param(:id, :integer, description: "#{resource_name.capitalize} ID")
+                                          .ok(@schema)
+                                          .not_found(error_schema, description: "#{resource_name.capitalize} not found")
+                                          .build
+
+          @endpoints << [endpoint_def, handler]
+        end
+
+        # Create new resource (POST /resources)
+        # @param options [Hash] Endpoint options
+        # @param handler [Proc] Request handler
+        def create(**options, &handler)
+          handler ||= proc { {} }
+
+          endpoint_def = @controller_class.POST(@base_path)
+                                          .summary(options[:summary] || "Create #{resource_name}")
+                                          .description(options[:description] || "Create a new #{resource_name}")
+                                          .json_body(@schema)
+                                          .created(@schema)
+                                          .bad_request(validation_error_schema, description: 'Validation error')
+                                          .build
+
+          @endpoints << [endpoint_def, handler]
+        end
+
+        # Update resource (PUT /resources/:id)
+        # @param options [Hash] Endpoint options
+        # @param handler [Proc] Request handler
+        def update(**options, &handler)
+          handler ||= proc { {} }
+
+          endpoint_def = @controller_class.PUT("#{@base_path}/:id")
+                                          .summary(options[:summary] || "Update #{resource_name}")
+                                          .description(options[:description] || "Update an existing #{resource_name}")
+                                          .path_param(:id, RapiTapir::Types.integer, description: "#{resource_name.capitalize} ID")
+                                          .json_body(@schema)
+                                          .ok(@schema)
+                                          .not_found(error_schema, description: "#{resource_name.capitalize} not found")
+                                          .bad_request(validation_error_schema, description: 'Validation error')
+                                          .build
+
+          @endpoints << [endpoint_def, handler]
+        end
+
+        # Delete resource (DELETE /resources/:id)
+        # @param options [Hash] Endpoint options
+        # @param handler [Proc] Request handler
+        def destroy(**options, &handler)
+          handler ||= proc { head :no_content }
+
+          endpoint_def = @controller_class.DELETE("#{@base_path}/:id")
+                                          .summary(options[:summary] || "Delete #{resource_name}")
+                                          .description(options[:description] || "Delete a #{resource_name}")
+                                          .path_param(:id, :integer, description: "#{resource_name.capitalize} ID")
+                                          .no_content
+                                          .not_found(error_schema, description: "#{resource_name.capitalize} not found")
+                                          .build
+
+          @endpoints << [endpoint_def, handler]
+        end
+
+        # Add custom endpoint to the resource
+        # @param method [Symbol] HTTP method
+        # @param path_suffix [String] Path suffix to append to base path
+        # @param options [Hash] Endpoint options
+        # @param handler [Proc] Request handler
+        def custom(method, path_suffix, **options, &handler)
+          full_path = path_suffix.start_with?('/') ? path_suffix : "#{@base_path}/#{path_suffix}"
+
+          endpoint_def = @controller_class.public_send(method.to_s.upcase, full_path)
+                                          .summary(options[:summary] || "Custom #{method.upcase} #{path_suffix}")
+                                          .description(options[:description] || "Custom endpoint for #{resource_name}")
+
+          # Apply any custom configuration
+          endpoint_def = options[:configure].call(endpoint_def) if options[:configure]
+
+          endpoint_def = endpoint_def.build
+
+          @endpoints << [endpoint_def, handler]
+        end
+
+        private
+
+        # Add pagination query parameters to an endpoint
+        # @param endpoint [RapiTapir::DSL::FluentEndpointBuilder] The endpoint builder
+        # @return [RapiTapir::DSL::FluentEndpointBuilder] The modified endpoint builder
+        def add_pagination_params(endpoint)
+          endpoint.query(:limit, RapiTapir::Types.optional(RapiTapir::Types.integer(minimum: 1, maximum: 100)),
+                         description: 'Maximum number of results')
+                  .query(:offset, RapiTapir::Types.optional(RapiTapir::Types.integer(minimum: 0)),
+                         description: 'Number of results to skip')
+        end
+
+        # Get the singular resource name from the base path
+        # @return [String] The singular resource name
+        def resource_name
+          @resource_name ||= @base_path.split('/').last.chomp('s')
+        end
+
+        # Standard error schema for 404 responses
+        # @return [RapiTapir::Types::Hash] Error schema
+        def error_schema
+          RapiTapir::Types.hash({
+                                  'error' => RapiTapir::Types.string
+                                })
+        end
+
+        # Validation error schema for 400 responses
+        # @return [RapiTapir::Types::Hash] Validation error schema
+        def validation_error_schema
+          RapiTapir::Types.hash({
+                                  'error' => RapiTapir::Types.string,
+                                  'details' => RapiTapir::Types.optional(RapiTapir::Types.array(RapiTapir::Types.string))
+                                })
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/server/rails/routes.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Server
+    module Rails
+      # Rails routes integration module
+      # Provides helpers for automatically generating routes from RapiTapir endpoint definitions
+      module Routes
+        # Generate routes for a RapiTapir Rails controller
+        # @param controller_class [Class] The controller class with RapiTapir endpoints
+        # @example
+        #   Rails.application.routes.draw do
+        #     rapitapir_routes_for UsersController
+        #   end
+        def rapitapir_routes_for(controller_class)
+          raise ArgumentError, "#{controller_class} must include RapiTapir::Server::Rails::Controller" unless controller_class.respond_to?(:rapitapir_endpoints)
+
+          controller_name = controller_class.controller_name
+
+          controller_class.rapitapir_endpoints.each do |action, endpoint_config|
+            endpoint_def = endpoint_config[:endpoint]
+            method = endpoint_def.method.downcase
+            path = convert_rapitapir_path_to_rails(endpoint_def.path)
+
+            # Generate the Rails route
+            public_send(method, path, to: "#{controller_name}##{action}",
+                                      as: route_name(controller_name, action, method))
+          end
+        end
+
+        # Generate all routes for multiple controllers
+        # @param controllers [Array<Class>] Array of controller classes
+        # @example
+        #   Rails.application.routes.draw do
+        #     rapitapir_routes_for_all [UsersController, BooksController, OrdersController]
+        #   end
+        def rapitapir_routes_for_all(controllers)
+          controllers.each do |controller_class|
+            rapitapir_routes_for(controller_class)
+          end
+        end
+
+        # Auto-discover and register all RapiTapir controllers in the application
+        # @example
+        #   Rails.application.routes.draw do
+        #     rapitapir_auto_routes
+        #   end
+        def rapitapir_auto_routes
+          # Find all controllers that include RapiTapir
+          controllers = ApplicationController.descendants.select do |klass|
+            klass.included_modules.include?(RapiTapir::Server::Rails::Controller) ||
+              klass < RapiTapir::Server::Rails::ControllerBase
+          end
+
+          rapitapir_routes_for_all(controllers)
+        end
+
+        private
+
+        # Convert RapiTapir path format to Rails route format
+        # @param rapitapir_path [String] Path with RapiTapir parameter syntax
+        # @return [String] Path with Rails parameter syntax
+        # @example
+        #   convert_rapitapir_path_to_rails('/users/:id')     # => '/users/:id'
+        #   convert_rapitapir_path_to_rails('/users/{id}')    # => '/users/:id'
+        def convert_rapitapir_path_to_rails(rapitapir_path)
+          # Convert {id} format to :id format for Rails
+          rapitapir_path.gsub(/\{(\w+)\}/, ':\1')
+        end
+
+        # Generate a route name for the endpoint
+        # @param controller_name [String] The controller name
+        # @param action [Symbol] The action name
+        # @param method [String] The HTTP method
+        # @return [Symbol] The route name
+        def route_name(controller_name, action, method)
+          base_name = controller_name.chomp('_controller')
+
+          case action
+          when :index
+            base_name.to_sym
+          when :show
+            singularize_name(base_name).to_sym
+          when :create
+            base_name.to_sym
+          when :update
+            singularize_name(base_name).to_sym
+          when :destroy
+            singularize_name(base_name).to_sym
+          else
+            :"#{method}_#{base_name}_#{action}"
+          end
+        end
+
+        # Simple singularization for route names
+        # @param name [String] The plural name
+        # @return [String] The singular name
+        def singularize_name(name)
+          # Simple singularization logic
+          if name.end_with?('ies')
+            "#{name.chomp('ies')}y"
+          elsif name.end_with?('s')
+            name.chomp('s')
+          else
+            name
+          end
+        end
+      end
+    end
+  end
+end
+
+# NOTE: Rails routes extension is handled in the rails_integration.rb file
+# to ensure proper timing with Rails application initialization

data/lib/rapitapir/server/rails_adapter.rb

@@ -3,15 +3,22 @@
 require_relative 'rails_controller'
 require_relative 'rails_adapter_class'
 
+# Load enhanced Rails integration components
+require_relative 'rails/controller_base'
+require_relative 'rails/configuration'
+require_relative 'rails/routes'
+require_relative 'rails/resource_builder'
+require_relative 'rails/documentation_helpers'
+
 module RapiTapir
   module Server
     # Rails integration module for RapiTapir
     #
     # Provides controller concerns and adapters for seamless integration with Rails applications.
-    # Split into separate files for better organization while maintaining compatibility.
+    # Includes the enhanced Rails integration with ControllerBase and auto-routing.
     module Rails
-      # Main module that includes both Controller concern and RailsAdapter class
-      # This maintains backward compatibility while organizing code better
+      # Main module that includes both legacy Controller concern and enhanced ControllerBase
+      # This maintains backward compatibility while providing the new enhanced features
     end
   end
 end

data/lib/rapitapir/server/rails_adapter_class.rb

@@ -13,9 +13,7 @@ module RapiTapir
 
         # Register an endpoint and generate Rails routes
         def register_endpoint(endpoint, controller_class, action_name)
-          unless endpoint.is_a?(RapiTapir::Core::Endpoint)
-            raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint'
-          end
+          raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint' unless endpoint.is_a?(RapiTapir::Core::Endpoint)
 
           endpoint.validate!
 

data/lib/rapitapir/server/rails_controller.rb

@@ -19,9 +19,7 @@ module RapiTapir
         class_methods do
           # Register an endpoint for this controller
           def rapitapir_endpoint(action_name, endpoint, &handler)
-            unless endpoint.is_a?(RapiTapir::Core::Endpoint)
-              raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint'
-            end
+            raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint' unless endpoint.is_a?(RapiTapir::Core::Endpoint)
 
             endpoint.validate!
 

data/lib/rapitapir/server/rails_integration.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Rails integration loader - ensures proper module initialization
+# Only loads if Rails and ActiveSupport are available
+
+# First, ensure the module structure exists
+module RapiTapir
+  module Server
+    module Rails
+      # Rails integration module for RapiTapir
+    end
+  end
+
+  # Define a method to load Rails integration when Rails becomes available
+  def self.load_rails_integration!
+    return if @rails_integration_loaded
+    return unless defined?(Rails) && defined?(ActiveSupport)
+
+    # Remove fallback ControllerBase if it exists
+    RapiTapir::Server::Rails.send(:remove_const, :ControllerBase) if RapiTapir::Server::Rails.const_defined?(:ControllerBase)
+
+    # Load Rails integration components in the correct order
+    require_relative 'rails_controller'
+    require_relative 'rails_adapter_class'
+    require_relative 'rails/configuration'
+    require_relative 'rails/routes'
+    require_relative 'rails/resource_builder'
+    require_relative 'rails/documentation_helpers'
+    require_relative 'rails/controller_base'
+
+    # Create Railtie for Rails integration
+    if defined?(Rails::Railtie) && !Object.const_defined?(:RapiTapirRailtie)
+      Object.const_set(:RapiTapirRailtie, Class.new(Rails::Railtie) do
+        initializer 'rapitapir.extend_routes', after: :initialize_routes do |app|
+          app.routes&.extend(RapiTapir::Server::Rails::Routes)
+        end
+      end)
+    end
+
+    @rails_integration_loaded = true
+  end
+end
+
+# Load immediately if Rails is already available
+if defined?(Rails) && defined?(ActiveSupport)
+  RapiTapir.load_rails_integration!
+else
+  # Rails not available - provide minimal fallback
+  module RapiTapir
+    module Server
+      module Rails
+        class ControllerBase
+          def self.method_missing(method, ...)
+            # Try to load Rails integration when accessed
+            RapiTapir.load_rails_integration!
+            if defined?(RapiTapir::Server::Rails::ControllerBase) && self.class != RapiTapir::Server::Rails::ControllerBase
+              return RapiTapir::Server::Rails::ControllerBase.send(method, ...)
+            end
+
+            raise NameError,
+                  'Rails integration not available. Please ensure Rails is loaded before requiring RapiTapir.'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/server/rails_response_handler.rb

@@ -8,14 +8,27 @@ module RapiTapir
         private
 
         def render_rapitapir_response(result, endpoint)
+          # Extract custom status code if provided
+          status_code = 200
+          response_data = result
+
+          if result.is_a?(Hash) && result.key?(:_status)
+            status_code = result[:_status]
+            response_data = result.except(:_status)
+          elsif result.is_a?(Hash) && result.key?('_status')
+            status_code = result['_status']
+            response_data = result.except('_status')
+          else
+            status_code = determine_rails_status_code(endpoint)
+          end
+
           output = endpoint.outputs.find { |o| o.kind == :json } || endpoint.outputs.first
-          status_code = determine_rails_status_code(endpoint)
 
           if output&.kind == :xml
-            render xml: result, status: status_code
+            render xml: response_data, status: status_code
           else
             # Default to JSON for nil output, :json kind, or unknown kinds
-            render json: result, status: status_code
+            render json: response_data, status: status_code
           end
         end
 

data/lib/rapitapir/server/sinatra_adapter.rb

@@ -24,9 +24,7 @@ module RapiTapir
 
       # Register an endpoint with automatic Sinatra route creation
       def register_endpoint(endpoint, handler = nil, &block)
-        unless endpoint.is_a?(RapiTapir::Core::Endpoint)
-          raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint'
-        end
+        raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint' unless endpoint.is_a?(RapiTapir::Core::Endpoint)
 
         endpoint.validate!
 
@@ -43,7 +41,6 @@ module RapiTapir
 
       private
 
-      # rubocop:disable Metrics/AbcSize
       def register_sinatra_route(endpoint_info)
         method_name = endpoint_info[:endpoint].method.to_s.downcase.to_sym
         path_pattern = convert_path_to_sinatra(endpoint_info[:endpoint].path)
@@ -61,7 +58,6 @@ module RapiTapir
           end
         end
       end
-      # rubocop:enable Metrics/AbcSize
 
       public
 
@@ -72,6 +68,18 @@ module RapiTapir
           processed_inputs = extract_sinatra_inputs(request, params, endpoint_data[:endpoint])
           result = @app.instance_exec(processed_inputs, &endpoint_data[:handler])
           send_successful_response(endpoint_data, result)
+        rescue RapiTapir::Types::CoercionError => e
+          detailed_error_response(400, 'Validation Error', e.reason, {
+                                    field: extract_field_from_error(e),
+                                    value: e.value,
+                                    expected_type: e.type
+                                  })
+        rescue RapiTapir::Types::ValidationError => e
+          detailed_error_response(400, 'Validation Error', e.message, {
+                                    errors: e.errors,
+                                    value: e.value,
+                                    expected_type: e.type.to_s
+                                  })
         rescue ArgumentError => e
           error_response(400, e.message)
         rescue StandardError => e
@@ -85,6 +93,22 @@ module RapiTapir
         [status_code, { 'Content-Type' => 'application/json' }, [error_data.to_json]]
       end
 
+      def detailed_error_response(status_code, error, message, details = {})
+        error_data = {
+          error: error,
+          message: message
+        }
+        error_data.merge!(details) if details.any?
+        [status_code, { 'Content-Type' => 'application/json' }, [error_data.to_json]]
+      end
+
+      def extract_field_from_error(error)
+        # Try to extract field name from error message
+        # Match both "Field 'field_name':" and "Required field 'field_name'"
+        match = error.reason.match(/(?:Field|Required field) '([^']+)'/)
+        match[1] if match
+      end
+
       def execute_endpoint_handler(endpoint_data, processed_inputs)
         case endpoint_data[:handler]
         when Proc

data/lib/rapitapir/server/sinatra_integration.rb

@@ -23,8 +23,8 @@ module RapiTapir
         end
 
         # Mount an endpoint in Sinatra
-        def mount_endpoint(endpoint, &handler)
-          rapitapir_adapter.mount(endpoint, &handler)
+        def mount_endpoint(endpoint, &)
+          rapitapir_adapter.mount(endpoint, &)
 
           # Register the route with Sinatra
           method_name = endpoint.method.to_s.downcase
@@ -42,8 +42,8 @@ module RapiTapir
         end
 
         # Register error handlers
-        def rapitapir_error(error_class, &handler)
-          rapitapir_adapter.on_error(error_class, &handler)
+        def rapitapir_error(error_class, &)
+          rapitapir_adapter.on_error(error_class, &)
         end
 
         # Generate OpenAPI spec for all mounted endpoints

data/lib/rapitapir/sinatra/extension.rb

@@ -29,9 +29,9 @@ module RapiTapir
       # Class methods added to the Sinatra application
       module ClassMethods
         # Configure RapiTapir integration
-        def rapitapir(&block)
+        def rapitapir(&)
           config = settings.rapitapir_config
-          config.instance_eval(&block) if block_given?
+          config.instance_eval(&) if block_given?
           setup_rapitapir_integration
         end