rapitapir 0.1.1 → 2.0.0

data/lib/rapitapir/core/endpoint.rb

@@ -14,6 +14,11 @@ module RapiTapir
     #     inputs: [path_param(:id, :integer)],
     #     outputs: [json_output(user_schema)]
     #   )
+    #     method: :get,
+    #     path: '/users/{id}',
+    #     inputs: [path_param(:id, :integer)],
+    #     outputs: [json_output(user_schema)]
+    #   )
     class Endpoint
       HTTP_METHODS = %i[get post put patch delete options head].freeze
 
@@ -77,6 +82,58 @@ module RapiTapir
         with_metadata(deprecated: flag_value)
       end
 
+      # Mark this endpoint for MCP export
+      def mcp_export
+        with_metadata(mcp_export: true)
+      end
+
+      # Returns true if this endpoint is marked for MCP export
+      def mcp_export?
+        metadata[:mcp_export] == true
+      end
+
+      # Configure RAG inference for this endpoint
+      def rag_inference(llm:, retrieval:, context_fields: [], config: {})
+        rag_config = {
+          llm: llm,
+          retrieval: retrieval,
+          context_fields: context_fields,
+          config: config
+        }
+        with_metadata(rag_inference: rag_config)
+      end
+
+      # Returns true if this endpoint has RAG inference configured
+      def rag_inference?
+        metadata.key?(:rag_inference)
+      end
+
+      # Get RAG configuration for this endpoint
+      def rag_config
+        metadata[:rag_inference]
+      end
+
+      # Configure LLM instruction generation for this endpoint
+      def llm_instruction(purpose:, fields: :all, **options)
+        llm_config = {
+          purpose: purpose,
+          fields: fields,
+          options: options
+        }
+
+        with_metadata(llm_instruction: llm_config)
+      end
+
+      # Check if this endpoint has LLM instruction generation configured
+      def llm_instruction?
+        metadata.key?(:llm_instruction)
+      end
+
+      # Get LLM instruction configuration for this endpoint
+      def llm_instruction_config
+        metadata[:llm_instruction]
+      end
+
       # Validate input/output types for a given input/output hash
       # Raises validation errors if invalid, returns true if valid
       def validate!(input_hash = {}, output_hash = {}) # rubocop:disable Naming/PredicateMethod
@@ -141,14 +198,10 @@ module RapiTapir
       def validate_outputs!(output_hash)
         outputs.each do |output|
           if output.type.is_a?(Hash)
-            unless output.valid_type?(output_hash)
-              raise TypeError, "Invalid output hash: expected #{output.type}, got #{output_hash}"
-            end
+            raise TypeError, "Invalid output hash: expected #{output.type}, got #{output_hash}" unless output.valid_type?(output_hash)
           else
             output_hash.each do |k, v|
-              unless output.valid_type?(v)
-                raise TypeError, "Invalid type for output '#{k}': expected #{output.type}, got #{v.class}"
-              end
+              raise TypeError, "Invalid type for output '#{k}': expected #{output.type}, got #{v.class}" unless output.valid_type?(v)
             end
           end
         end

data/lib/rapitapir/core/enhanced_endpoint.rb

@@ -210,17 +210,13 @@ module RapiTapir
 
       def validate_security_schemes!
         security_schemes.each do |scheme|
-          unless %i[bearer api_key basic].include?(scheme.options[:auth_type])
-            raise ArgumentError, "Unknown authentication type: #{scheme.options[:auth_type]}"
-          end
+          raise ArgumentError, "Unknown authentication type: #{scheme.options[:auth_type]}" unless %i[bearer api_key basic].include?(scheme.options[:auth_type])
         end
       end
 
       def validate_type_consistency!
         inputs.each do |input|
-          unless input.type.respond_to?(:validate)
-            raise ArgumentError, "Input '#{input.name}' type does not support validation"
-          end
+          raise ArgumentError, "Input '#{input.name}' type does not support validation" unless input.type.respond_to?(:validate)
         end
 
         outputs.each do |output|

data/lib/rapitapir/dsl/fluent_endpoint_builder.rb

@@ -159,6 +159,9 @@ module RapiTapir
         copy_with(errors: @errors + [error])
       end
 
+      # Alias for compatibility with Core::Endpoint
+      alias error_out error_response
+
       def bad_request(type_def = nil, **options)
         error_response(400, type_def, **options)
       end
@@ -311,6 +314,56 @@ module RapiTapir
           **options
         )
       end
+
+      public
+
+      # AI/MCP Extensions
+      def mcp_export
+        copy_with(metadata: @metadata.merge(mcp_export: true))
+      end
+
+      def mcp_export?
+        @metadata[:mcp_export] == true
+      end
+
+      def rag_inference(llm:, retrieval:, context_fields: [], config: {})
+        copy_with(metadata: @metadata.merge(
+          rag_inference: true,
+          rag_config: {
+            llm: llm,
+            retrieval: retrieval,
+            context_fields: context_fields,
+            config: config
+          }
+        ))
+      end
+
+      def rag_inference?
+        @metadata[:rag_inference] == true
+      end
+
+      def rag_config
+        @metadata[:rag_config]
+      end
+
+      # LLM Instruction Generation
+      def llm_instruction(purpose:, fields: :all, **options)
+        copy_with(metadata: @metadata.merge(
+          llm_instruction: {
+            purpose: purpose,
+            fields: fields,
+            options: options
+          }
+        ))
+      end
+
+      def llm_instruction?
+        @metadata.key?(:llm_instruction)
+      end
+
+      def llm_instruction_config
+        @metadata[:llm_instruction]
+      end
     end
   end
 end

data/lib/rapitapir/endpoint_registry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  # Global endpoint registry for collecting and managing endpoints
+  # Provides a central place to register and discover endpoints for CLI operations
+  class EndpointRegistry
+    @endpoints = []
+    @mutex = Mutex.new
+
+    class << self
+      # Register an endpoint in the global registry
+      def register(endpoint)
+        @mutex.synchronize do
+          @endpoints << endpoint unless @endpoints.include?(endpoint)
+        end
+      end
+
+      # Get all registered endpoints
+      def all
+        @mutex.synchronize { @endpoints.dup }
+      end
+
+      # Get only endpoints marked for MCP export
+      def mcp_endpoints
+        @mutex.synchronize { @endpoints.select(&:mcp_export?) }
+      end
+
+      # Clear all registered endpoints (useful for testing)
+      def clear!
+        @mutex.synchronize { @endpoints.clear }
+      end
+
+      # Register multiple endpoints at once
+      def register_all(endpoints)
+        endpoints.each { |endpoint| register(endpoint) }
+      end
+
+      # Find endpoints by method and path pattern
+      def find_by(method: nil, path: nil)
+        results = all
+        results = results.select { |ep| ep.method == method } if method
+        results = results.select { |ep| ep.path&.include?(path) } if path
+        results
+      end
+    end
+  end
+end

data/lib/rapitapir/observability/health_check.rb

@@ -73,8 +73,8 @@ module RapiTapir
           register_default_checks
         end
 
-        def register(name, description = nil, &block)
-          @checks << Check.new(name, description, &block)
+        def register(name, description = nil, &)
+          @checks << Check.new(name, description, &)
         end
 
         def run_all
@@ -210,9 +210,9 @@ module RapiTapir
           @endpoint_path = endpoint
         end
 
-        def register(name, description = nil, &block)
+        def register(name, description = nil, &)
           @registry ||= Registry.new
-          @registry.register(name, description, &block)
+          @registry.register(name, description, &)
         end
 
         def endpoint

data/lib/rapitapir/observability/logging.rb

@@ -22,24 +22,24 @@ module RapiTapir
           @logger.formatter = @formatter
         end
 
-        def debug(message = nil, **fields, &block)
-          log(:debug, message, **fields, &block)
+        def debug(message = nil, **fields, &)
+          log(:debug, message, **fields, &)
         end
 
-        def info(message = nil, **fields, &block)
-          log(:info, message, **fields, &block)
+        def info(message = nil, **fields, &)
+          log(:info, message, **fields, &)
         end
 
-        def warn(message = nil, **fields, &block)
-          log(:warn, message, **fields, &block)
+        def warn(message = nil, **fields, &)
+          log(:warn, message, **fields, &)
         end
 
-        def error(message = nil, **fields, &block)
-          log(:error, message, **fields, &block)
+        def error(message = nil, **fields, &)
+          log(:error, message, **fields, &)
         end
 
-        def fatal(message = nil, **fields, &block)
-          log(:fatal, message, **fields, &block)
+        def fatal(message = nil, **fields, &)
+          log(:fatal, message, **fields, &)
         end
 
         def log_request(**options)

data/lib/rapitapir/schema.rb

@@ -24,9 +24,9 @@ module RapiTapir
     end
 
     # Define a schema using a block
-    def self.define(&block)
+    def self.define(&)
       builder = SchemaBuilder.new
-      builder.instance_eval(&block)
+      builder.instance_eval(&)
       builder.build
     end
 

data/lib/rapitapir/server/rack_adapter.rb

@@ -19,9 +19,7 @@ module RapiTapir
 
       # Register an endpoint with the adapter
       def register_endpoint(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)
         raise ArgumentError, 'Handler must respond to call' unless handler.respond_to?(:call)
 
         endpoint.validate!

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Server
+    module Rails
+      # Simple configuration class for Rails integration
+      # Provides basic configuration options needed for Rails controllers
+      class Configuration
+        attr_accessor :docs_path, :openapi_path, :health_check_enabled, :health_check_path
+        attr_reader :api_info, :servers, :public_paths, :auth_schemes
+
+        def initialize
+          @api_info = {
+            title: 'API Documentation',
+            description: 'Generated with RapiTapir',
+            version: '1.0.0'
+          }
+          @servers = []
+          @public_paths = []
+          @auth_schemes = {}
+          @docs_path = '/docs'
+          @openapi_path = '/openapi.json'
+          @health_check_enabled = false
+          @health_check_path = '/health'
+        end
+
+        # API Information configuration
+        def info(title: nil, description: nil, version: nil, **options)
+          @api_info[:title] = title if title
+          @api_info[:description] = description if description
+          @api_info[:version] = version if version
+          @api_info.merge!(options)
+        end
+
+        # Server configuration
+        def server(url:, description: nil)
+          @servers << { url: url, description: description }.compact
+        end
+
+        # Add paths that don't require authentication
+        def add_public_paths(*paths)
+          @public_paths.concat(paths.flatten.map(&:to_s))
+        end
+
+        # Authentication scheme management
+        def add_auth_scheme(name, scheme)
+          @auth_schemes[name] = scheme
+        end
+
+        def get_auth_scheme(name)
+          @auth_schemes[name]
+        end
+
+        # Enable development defaults (docs endpoints, etc.)
+        def development_defaults!
+          # This would set up automatic documentation endpoints
+          # For now, just enable health checks
+          @health_check_enabled = true
+
+          # Enable docs
+          enable_docs
+        end
+
+        # Enable documentation endpoints
+        def enable_docs(path: '/docs', openapi_path: '/openapi.json')
+          @docs_path = path
+          @openapi_path = openapi_path
+        end
+
+        # Check if docs are enabled
+        def docs_enabled?
+          !@docs_path.nil?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative '../rails_controller'
+require_relative '../../dsl/http_verbs'
+require_relative '../../types'
+require_relative 'resource_builder'
+require_relative 'configuration'
+
+module RapiTapir
+  module Server
+    module Rails
+      # Enhanced Rails controller base class providing Sinatra-like experience
+      #
+      # This class bridges the gap between Sinatra's elegant DSL and Rails conventions,
+      # offering the same clean syntax that Sinatra developers enjoy.
+      #
+      # @example Basic usage
+      #   class UsersController < RapiTapir::Server::Rails::ControllerBase
+      #     rapitapir do
+      #       info(title: 'Users API', version: '1.0.0')
+      #       development_defaults!
+      #     end
+      #
+      #     USER_SCHEMA = T.hash({
+      #       "id" => T.integer,
+      #       "name" => T.string,
+      #       "email" => T.email
+      #     })
+      #
+      #     endpoint(
+      #       GET('/users')
+      #         .summary('List users')
+      #         .ok(T.array(USER_SCHEMA))
+      #         .build
+      #     ) { User.all.map(&:attributes) }
+      #   end
+      class ControllerBase < ActionController::Base
+        include RapiTapir::Server::Rails::Controller
+        extend RapiTapir::DSL::HTTPVerbs
+
+        # Make T shortcut available in Rails controllers
+        T = RapiTapir::Types
+
+        class << self
+          # Configure RapiTapir for this controller
+          # Similar to Sinatra's rapitapir block
+          #
+          # @param block [Proc] Configuration block
+          # @example
+          #   rapitapir do
+          #     info(title: 'My API', version: '1.0.0')
+          #     development_defaults!
+          #   end
+          def rapitapir(&)
+            @rapitapir_config = Configuration.new
+            @rapitapir_config.instance_eval(&) if block_given?
+            setup_default_features
+          end
+
+          # Define an endpoint with automatic action generation
+          # This method creates both the endpoint definition and the corresponding Rails action
+          #
+          # @param endpoint_definition [RapiTapir::Core::Endpoint] The endpoint definition
+          # @param block [Proc] The endpoint handler
+          # @example
+          #   endpoint(
+          #     GET('/users/:id')
+          #       .summary('Get user')
+          #       .path_param(:id, T.integer)
+          #       .ok(USER_SCHEMA)
+          #       .build
+          #   ) do |inputs|
+          #     User.find(inputs[:id]).attributes
+          #   end
+          def endpoint(endpoint_definition, &)
+            action_name = derive_action_name(endpoint_definition.path, endpoint_definition.method)
+
+            # Register endpoint with the Rails controller mixin
+            rapitapir_endpoint(action_name, endpoint_definition, &)
+
+            # Auto-generate Rails controller action that passes the correct action name
+            define_method(action_name) do
+              process_rapitapir_endpoint(action_name)
+            end
+          end
+
+          # Create RESTful resource endpoints with CRUD operations
+          # Mirrors Sinatra's api_resource functionality for Rails
+          #
+          # @param path [String] Base path for the resource
+          # @param schema [Object] Schema for the resource
+          # @param block [Proc] Resource configuration block
+          # @example
+          #   api_resource '/users', schema: USER_SCHEMA do
+          #     crud do
+          #       index { User.all.map(&:attributes) }
+          #       show { |inputs| User.find(inputs[:id]).attributes }
+          #       create { |inputs| User.create!(inputs[:body]).attributes }
+          #     end
+          #   end
+          def api_resource(path, schema:, &block)
+            resource_builder = ResourceBuilder.new(self, path, schema)
+            resource_builder.instance_eval(&block)
+
+            # Generate all CRUD endpoints and actions automatically
+            resource_builder.endpoints.each do |endpoint_def, handler|
+              endpoint(endpoint_def, &handler)
+            end
+          end
+
+          # Enhanced HTTP verb methods that return FluentEndpointBuilder
+          # These override the mixin methods to ensure proper scoping
+          #
+          # @param path [String] The endpoint path
+          # @return [RapiTapir::DSL::FluentEndpointBuilder] Builder for method chaining
+          def GET(path)
+            RapiTapir.get(path)
+          end
+
+          def POST(path)
+            RapiTapir.post(path)
+          end
+
+          def PUT(path)
+            RapiTapir.put(path)
+          end
+
+          def PATCH(path)
+            RapiTapir.patch(path)
+          end
+
+          def DELETE(path)
+            RapiTapir.delete(path)
+          end
+
+          def HEAD(path)
+            RapiTapir.head(path)
+          end
+
+          def OPTIONS(path)
+            RapiTapir.options(path)
+          end
+
+          private
+
+          # Set up default features similar to Sinatra extension
+          def setup_default_features
+            # Future: Auto-setup CORS, docs, health checks like Sinatra
+            # For now, we'll focus on the core functionality
+          end
+
+          # Derive Rails action name from HTTP method and path
+          # Follows Rails conventions for RESTful routes
+          #
+          # @param path [String] The endpoint path
+          # @param method [Symbol] The HTTP method
+          # @return [Symbol] The Rails action name
+          def derive_action_name(path, method)
+            # For custom endpoints, always derive from path to avoid conflicts
+            path_segments = path.split('/').reject(&:empty?)
+
+            return method.to_s.downcase.to_sym if path_segments.empty?
+
+            # Get the main path segment (not parameters)
+            main_segment = nil
+            path_segments.each do |segment|
+              unless segment.start_with?(':') || segment.start_with?('{')
+                main_segment = segment
+                break
+              end
+            end
+
+            if main_segment
+              # Create action name from method + segment to ensure uniqueness
+              :"#{method.to_s.downcase}_#{main_segment}"
+            else
+              # Fallback to method name
+              method.to_s.downcase.to_sym
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative '../../openapi/schema_generator'
+require_relative '../../sinatra/swagger_ui_generator'
+
+module RapiTapir
+  module Server
+    module Rails
+      # Documentation helpers for Rails controllers
+      module DocumentationHelpers
+        # Generate OpenAPI specification from Rails controller endpoints
+        def generate_openapi_spec_for_controller(controller_class, config = {})
+          endpoints = []
+
+          endpoints = controller_class.rapitapir_endpoints.values.map { |ep_config| ep_config[:endpoint] } if controller_class.respond_to?(:rapitapir_endpoints)
+
+          info = {
+            title: 'API Documentation',
+            version: '1.0.0',
+            description: 'Generated with RapiTapir for Rails'
+          }.merge(config[:info] || {})
+
+          servers = config[:servers] || [
+            {
+              url: 'http://localhost:9292',
+              description: 'Development server (Rails)'
+            }
+          ]
+
+          generator = RapiTapir::OpenAPI::SchemaGenerator.new(
+            endpoints: endpoints,
+            info: info,
+            servers: servers
+          )
+
+          generator.generate
+        end
+
+        # Generate Swagger UI HTML for Rails
+        def generate_swagger_ui_html(openapi_path, api_info)
+          RapiTapir::Sinatra::SwaggerUIGenerator.new(openapi_path, api_info).generate
+        end
+
+        # Create documentation routes for a Rails controller
+        def add_documentation_routes(controller_class, config = {})
+          docs_path = config[:docs_path] || '/docs'
+          openapi_path = config[:openapi_path] || '/openapi.json'
+
+          # OpenAPI JSON endpoint
+          get openapi_path, to: proc { |_env|
+            spec = RapiTapir::Server::Rails::DocumentationHelpers.generate_openapi_spec_for_controller(controller_class, config)
+            [
+              200,
+              { 'Content-Type' => 'application/json' },
+              [JSON.pretty_generate(spec)]
+            ]
+          }
+
+          # Swagger UI endpoint
+          get docs_path, to: proc { |_env|
+            api_info = config[:info] || { title: 'API Documentation' }
+            html = RapiTapir::Server::Rails::DocumentationHelpers.generate_swagger_ui_html(openapi_path, api_info)
+            [
+              200,
+              { 'Content-Type' => 'text/html' },
+              [html]
+            ]
+          }
+        end
+
+        # Module methods for static access
+        module_function :generate_openapi_spec_for_controller, :generate_swagger_ui_html
+      end
+    end
+  end
+end