rapitapir 0.1.2 → 2.0.0

data/examples/rails/detailed_test.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Detailed Rails integration test
+
+puts "🧪 Testing Rails Integration in Detail..."
+puts "=" * 50
+
+begin
+  puts "\n1. Loading Rails app..."
+  require_relative 'hello_world_app'
+  puts "✅ App loaded: #{HelloWorldRailsApp.class}"
+  
+  puts "\n2. Checking controller endpoints..."
+  if HelloWorldController.respond_to?(:rapitapir_endpoints)
+    endpoints = HelloWorldController.rapitapir_endpoints
+    puts "✅ Found #{endpoints.count} endpoints:"
+    endpoints.each do |action, config|
+      endpoint = config[:endpoint]
+      puts "   #{endpoint.method} #{endpoint.path} => #{action}"
+    end
+  else
+    puts "❌ No rapitapir_endpoints found"
+  end
+  
+  puts "\n3. Checking routes..."
+  routes = HelloWorldRailsApp.routes.routes
+  puts "✅ Found #{routes.count} routes:"
+  routes.each do |route|
+    puts "   #{route.verb} #{route.path.spec} => #{route.defaults[:controller]}##{route.defaults[:action]}"
+  end
+  
+  puts "\n4. Testing controller instantiation..."
+  controller = HelloWorldController.new
+  puts "✅ Controller instantiated: #{controller.class}"
+  
+  puts "\n5. Testing Rails engine..."
+  app = HelloWorldRailsApp
+  puts "✅ Rails app ready: #{app}"
+  
+  puts "\n🎉 Rails integration appears to be working!"
+  
+rescue => e
+  puts "❌ Error: #{e.message}"
+  puts e.backtrace[0..5].join("\n")
+end

data/examples/rails/enhanced_users_controller.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+# Enhanced Rails controller example using RapiTapir's new base class
+# This demonstrates the improved developer experience that matches Sinatra's elegance
+#
+# Usage in a Rails app:
+# 1. Add this file to app/controllers/
+# 2. Add routes using the automatic route generator
+# 3. That's it! No boilerplate needed.
+
+require_relative '../../lib/rapitapir'
+require_relative '../../lib/rapitapir/server/rails/controller_base'
+
+class EnhancedUsersController < RapiTapir::Server::Rails::ControllerBase
+  # Configure RapiTapir - same clean syntax as Sinatra
+  rapitapir do
+    info(
+      title: 'Enhanced Users API',
+      description: 'A clean, type-safe user management API built with RapiTapir for Rails',
+      version: '1.0.0'
+    )
+    # Future: development_defaults! will auto-setup CORS, docs, health checks
+  end
+
+  # Define schema using T shortcut (automatically available!)
+  USER_SCHEMA = T.hash({
+    "id" => T.integer,
+    "name" => T.string(min_length: 1, max_length: 100),
+    "email" => T.email,
+    "active" => T.boolean,
+    "created_at" => T.datetime,
+    "updated_at" => T.datetime
+  })
+
+  USER_CREATE_SCHEMA = T.hash({
+    "name" => T.string(min_length: 1, max_length: 100),
+    "email" => T.email,
+    "active" => T.optional(T.boolean)
+  })
+
+  USER_UPDATE_SCHEMA = T.hash({
+    "name" => T.optional(T.string(min_length: 1, max_length: 100)),
+    "email" => T.optional(T.email),
+    "active" => T.optional(T.boolean)
+  })
+
+  before_action :setup_users_data
+
+  # Option 1: Use the enhanced api_resource DSL (recommended for CRUD)
+  api_resource '/users', schema: USER_SCHEMA do
+    crud do
+      index do
+        # Access Rails helpers and instance variables naturally
+        users = @users.values
+        
+        # Apply optional filtering (Rails-style)
+        users = users.select { |u| u[:active] } if params[:active] == 'true'
+        
+        # Simple pagination
+        limit = params[:limit]&.to_i || 20
+        offset = params[:offset]&.to_i || 0
+        
+        users[offset, limit] || []
+      end
+      
+      show do |inputs|
+        user = @users[inputs[:id]]
+        
+        # Rails-style error handling
+        if user.nil?
+          render json: { error: 'User not found' }, status: :not_found
+          return
+        end
+        
+        user
+      end
+      
+      create do |inputs|
+        new_id = (@users.keys.max || 0) + 1
+        
+        new_user = {
+          id: new_id,
+          name: inputs[:body]['name'],
+          email: inputs[:body]['email'],
+          active: inputs[:body]['active'] || true,
+          created_at: Time.now.iso8601,
+          updated_at: Time.now.iso8601
+        }
+        
+        @users[new_id] = new_user
+        
+        # Rails-style status setting
+        response.status = 201
+        new_user
+      end
+      
+      update do |inputs|
+        user = @users[inputs[:id]]
+        
+        if user.nil?
+          render json: { error: 'User not found' }, status: :not_found
+          return
+        end
+        
+        # Update fields
+        update_data = inputs[:body]
+        user[:name] = update_data['name'] if update_data['name']
+        user[:email] = update_data['email'] if update_data['email']
+        user[:active] = update_data['active'] if update_data.key?('active')
+        user[:updated_at] = Time.now.iso8601
+        
+        @users[inputs[:id]] = user
+        user
+      end
+      
+      destroy do |inputs|
+        user = @users[inputs[:id]]
+        
+        if user.nil?
+          render json: { error: 'User not found' }, status: :not_found
+          return
+        end
+        
+        @users.delete(inputs[:id])
+        
+        # Rails-style head response
+        head :no_content
+      end
+    end
+  end
+
+  # Option 2: Individual endpoint definitions with enhanced HTTP verb DSL
+  endpoint(
+    GET('/users/active')
+      .summary('Get active users')
+      .description('Retrieve a list of all active users in the system')
+      .tags('Users')
+      .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)), description: 'Maximum number of results')
+      .ok(T.array(USER_SCHEMA))
+      .build
+  ) do |inputs|
+    active_users = @users.values.select { |u| u[:active] }
+    limit = inputs[:limit] || 20
+    active_users.first(limit)
+  end
+
+  endpoint(
+    POST('/users/bulk')
+      .summary('Create multiple users')
+      .description('Create multiple users in a single request')
+      .tags('Users')
+      .json_body(T.array(USER_CREATE_SCHEMA))
+      .created(T.array(USER_SCHEMA))
+      .bad_request(T.hash({
+        "error" => T.string,
+        "failed_users" => T.array(T.hash({
+          "index" => T.integer,
+          "errors" => T.array(T.string)
+        }))
+      }))
+      .build
+  ) do |inputs|
+    created_users = []
+    failed_users = []
+    
+    inputs[:body].each_with_index do |user_data, index|
+      # Simple validation
+      errors = []
+      errors << 'Name is required' if user_data['name'].nil? || user_data['name'].empty?
+      errors << 'Email is required' if user_data['email'].nil? || user_data['email'].empty?
+      errors << 'Email already exists' if @users.values.any? { |u| u[:email] == user_data['email'] }
+      
+      if errors.any?
+        failed_users << { index: index, errors: errors }
+        next
+      end
+      
+      new_id = (@users.keys.max || 0) + 1
+      new_user = {
+        id: new_id,
+        name: user_data['name'],
+        email: user_data['email'],
+        active: user_data['active'] || true,
+        created_at: Time.now.iso8601,
+        updated_at: Time.now.iso8601
+      }
+      
+      @users[new_id] = new_user
+      created_users << new_user
+    end
+    
+    if failed_users.any?
+      render json: {
+        error: 'Some users could not be created',
+        failed_users: failed_users
+      }, status: :bad_request
+      return
+    end
+    
+    response.status = 201
+    created_users
+  end
+
+  endpoint(
+    GET('/users/search')
+      .summary('Search users')
+      .description('Search users by name or email')
+      .tags('Users', 'Search')
+      .query(:q, T.string(min_length: 1), description: 'Search query')
+      .query(:fields, T.optional(T.array(T.string(enum: %w[name email]))), description: 'Fields to search in')
+      .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)), description: 'Maximum number of results')
+      .ok(T.array(USER_SCHEMA))
+      .bad_request(T.hash({ "error" => T.string }))
+      .build
+  ) do |inputs|
+    query = inputs[:q].downcase
+    fields = inputs[:fields] || %w[name email]
+    limit = inputs[:limit] || 20
+    
+    results = @users.values.select do |user|
+      fields.any? do |field|
+        user[field.to_sym]&.downcase&.include?(query)
+      end
+    end
+    
+    results.first(limit)
+  end
+
+  private
+
+  def setup_users_data
+    @users = {
+      1 => {
+        id: 1,
+        name: 'John Doe',
+        email: 'john@example.com',
+        active: true,
+        created_at: 1.week.ago.iso8601,
+        updated_at: 1.week.ago.iso8601
+      },
+      2 => {
+        id: 2,
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        active: true,
+        created_at: 3.days.ago.iso8601,
+        updated_at: 3.days.ago.iso8601
+      },
+      3 => {
+        id: 3,
+        name: 'Bob Wilson',
+        email: 'bob@example.com',
+        active: false,
+        created_at: 1.day.ago.iso8601,
+        updated_at: 1.day.ago.iso8601
+      }
+    }
+  end
+end
+
+# Example routes configuration for config/routes.rb:
+#
+# Rails.application.routes.draw do
+#   # Option 1: Automatic route generation for specific controller
+#   rapitapir_routes_for EnhancedUsersController
+#   
+#   # Option 2: Auto-discover all RapiTapir controllers
+#   rapitapir_auto_routes
+#   
+#   # Option 3: Manual routes (still works)
+#   resources :enhanced_users, only: [:index, :show, :create, :update, :destroy] do
+#     collection do
+#       get :active
+#       post :bulk
+#       get :search
+#     end
+#   end
+# end

data/examples/rails/final_server_test.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test the Rails server startup
+
+puts "🧪 Testing Rails Server Startup (Final)..."
+puts "=" * 45
+
+begin
+  puts "\n1. Loading Rails app..."
+  require_relative 'hello_world_app'
+  puts "✅ App loaded successfully"
+  
+  puts "\n2. Testing direct app call..."
+  env = {
+    'REQUEST_METHOD' => 'GET',
+    'PATH_INFO' => '/hello',
+    'QUERY_STRING' => 'name=Test',
+    'HTTP_HOST' => 'localhost:9292',
+    'rack.url_scheme' => 'http',
+    'rack.input' => StringIO.new(''),
+    'rack.errors' => $stderr,
+    'rack.version' => [1, 3],
+    'rack.multithread' => true,
+    'rack.multiprocess' => false,
+    'rack.run_once' => false
+  }
+  
+  require 'stringio'
+  env['rack.input'] = StringIO.new('')
+  
+  status, headers, body = HelloWorldRailsApp.call(env)
+  puts "✅ App responds: status=#{status}"
+  
+  puts "\n3. Testing WEBrick server creation..."
+  require 'webrick'
+  server = WEBrick::HTTPServer.new(
+    Port: 9293,  # Different port for testing
+    Host: 'localhost'
+  )
+  puts "✅ WEBrick server created"
+  
+  puts "\n🎉 Rails server setup is ready!"
+  puts "\n🚀 The server should start successfully."
+  puts "📝 Run: ruby examples/rails/hello_world_app.rb"
+  
+rescue => e
+  puts "❌ Error: #{e.message}"
+  puts e.backtrace[0..3].join("\n")
+end

data/examples/rails/hello_world_app.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Minimal Rails Application for Hello World RapiTapir Demo
+# This creates a minimal Rails app to demonstrate the Hello World controller
+
+require 'rails'
+require 'action_controller/railtie'
+require 'json'
+
+# Minimal Rails application
+class HelloWorldRailsApp < Rails::Application
+  config.load_defaults Rails::VERSION::STRING.to_f
+  config.api_only = true
+  config.eager_load = false
+  config.cache_classes = false
+  config.secret_key_base = 'dummy_secret_for_demo'
+  
+  # Disable unnecessary middleware for demo
+  config.middleware.delete ActionDispatch::Cookies
+  config.middleware.delete ActionDispatch::Session::CookieStore
+  config.middleware.delete ActionDispatch::Flash
+  
+  # CORS for development (optional)
+  config.middleware.insert_before 0, Rack::Cors do
+    allow do
+      origins '*'
+      resource '*', headers: :any, methods: [:get, :post, :put, :patch, :delete, :options, :head]
+    end
+  end if defined?(Rack::Cors)
+end
+
+# Initialize the Rails application
+HelloWorldRailsApp.initialize!
+
+# Load our controller
+require_relative 'hello_world_controller'
+
+# Load routes helper and include it in Rails routes
+require_relative '../../lib/rapitapir/server/rails/routes'
+require_relative '../../lib/rapitapir/server/rails/documentation_helpers'
+ActionDispatch::Routing::Mapper.include(RapiTapir::Server::Rails::Routes)
+ActionDispatch::Routing::Mapper.include(RapiTapir::Server::Rails::DocumentationHelpers)
+
+# Define routes
+HelloWorldRailsApp.routes.draw do
+  # Auto-generate routes from RapiTapir endpoints
+  rapitapir_routes_for HelloWorldController
+  
+  # Documentation endpoints
+  add_documentation_routes(
+    HelloWorldController, 
+    {
+      docs_path: '/docs',
+      openapi_path: '/openapi.json',
+      info: {
+        title: 'Hello World Rails API',
+        version: '1.0.0',
+        description: 'A beautiful Rails API built with RapiTapir - same elegant syntax as Sinatra!'
+      },
+      servers: [
+        {
+          url: 'http://localhost:9292',
+          description: 'Development server (Rails + RapiTapir)'
+        }
+      ]
+    }
+  )
+  
+  # Welcome page
+  root 'hello_world#welcome'
+  
+  # Manual health check (for demo purposes)
+  get '/manual-health', to: proc { |env|
+    [200, {'Content-Type' => 'application/json'}, 
+     [{ status: 'healthy', message: 'Manual route working!' }.to_json]]
+  }
+end
+
+# If running this file directly
+if __FILE__ == $PROGRAM_NAME
+  require 'rack'
+  
+  puts "\n🌟 Hello World Rails API with RapiTapir"
+  puts "🚀 Clean syntax: class HelloWorldController < RapiTapir::Server::Rails::ControllerBase"
+  puts "🔗 Enhanced Rails integration with Sinatra-like elegance"
+  puts ""
+  puts "📋 Available endpoints:"
+  puts "   GET  /                      - Welcome message"
+  puts "   GET  /hello?name=YourName   - Personalized greeting" 
+  puts "   GET  /greet/:language       - Multilingual greetings"
+  puts "   POST /greetings             - Create custom greeting"
+  puts "   GET  /health                - Health check"
+  puts "   GET  /docs                  - 📖 Interactive API Documentation (Swagger UI)"
+  puts "   GET  /openapi.json          - 🔧 OpenAPI 3.0 Specification"
+  puts ""
+  puts "🌐 Starting server on http://localhost:9292"
+  puts "❤️  Try: curl http://localhost:9292/hello?name=Developer"
+  puts "🌍 Try: curl http://localhost:9292/greet/spanish"
+  puts ""
+  puts "✨ Beautiful, type-safe Rails API with RapiTapir integration!"
+  puts ""
+  puts "🌐 Starting server on http://localhost:9292"
+  puts "📖 Try these endpoints:"
+  puts "   curl 'http://localhost:9292/hello?name=Developer'"
+  puts "   curl 'http://localhost:9292/greet/spanish'"
+  puts "   curl -X POST 'http://localhost:9292/greetings' -H 'Content-Type: application/json' -d '{\"name\":\"Rails\"}'"
+  puts "   open http://localhost:9292/docs  # 📖 Interactive API Documentation!"
+  puts ""
+  
+  # Start server using Rackup (modern Rack)
+  require 'rackup/handler/webrick'
+  
+  puts "🚀 Starting server with Rackup..."
+  
+  Rackup::Handler::WEBrick.run(HelloWorldRailsApp, Port: 9292, Host: 'localhost')
+end

data/examples/rails/hello_world_controller.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# RapiTapir Rails Integration - Hello World Example
+#
+# The most minimal example showing how to create a beautiful, type-safe API
+# with automatic OpenAPI documentation using Rails and the enhanced RapiTapir integration!
+
+require_relative '../../lib/rapitapir'
+require_relative '../../lib/rapitapir/server/rails/controller_base'
+
+# Your entire Rails API controller in under 20 lines! 🚀
+class HelloWorldController < RapiTapir::Server::Rails::ControllerBase
+
+  # One-line API configuration - same as Sinatra!
+  rapitapir do
+    info(title: 'Hello World Rails API', version: '1.0.0')
+    development_defaults! # Enable docs, health checks, CORS, etc.
+  end
+
+  # Hello World endpoint - beautifully typed and documented using enhanced DSL
+  endpoint(
+    GET('/hello')
+      .query(:name, T.optional(T.string), description: 'Name to greet')
+      .summary('Say hello to someone')
+      .description('Returns a personalized greeting with Rails magic')
+      .tags('Greetings')
+      .ok(T.hash({
+        'message' => T.string,
+        'timestamp' => T.string,
+        'framework' => T.string
+      }))
+      .build
+  ) do |inputs|
+    name = inputs[:name] || 'Rails Developer'
+    
+    # Return data - let RapiTapir handle the rendering
+    {
+      message: "Hello, #{name}! Welcome to RapiTapir with Rails!",
+      timestamp: Time.now.iso8601,
+      framework: 'Rails + RapiTapir'
+    }
+  end
+
+  # Another endpoint showing path parameters with enhanced DSL
+  endpoint(
+    GET('/greet/:language')
+      .path_param(:language, T.string, description: 'Language for greeting')
+      .summary('Multilingual greeting')
+      .description('Get a greeting in different languages using Rails')
+      .tags('Greetings', 'i18n')
+      .ok(T.hash({ 
+        'greeting' => T.string,
+        'language' => T.string,
+        'powered_by' => T.string
+      }))
+      .not_found(T.hash({ 'error' => T.string }))
+      .build
+  ) do |inputs|
+    greetings = {
+      'english' => 'Hello!',
+      'spanish' => '¡Hola!',
+      'french' => 'Bonjour!',
+      'italian' => 'Ciao!',
+      'german' => 'Hallo!',
+      'japanese' => 'こんにちは!',
+      'portuguese' => 'Olá!',
+      'russian' => 'Привет!'
+    }
+
+    language = inputs[:language].downcase
+    greeting = greetings[language]
+    
+    if greeting.nil?
+      # Return error response structure
+      { error: "Language '#{inputs[:language]}' not supported", _status: 404 }
+    else
+      # Return success response
+      {
+        greeting: greeting,
+        language: language.capitalize,
+        powered_by: 'RapiTapir + Rails'
+      }
+    end
+  end
+
+  # Demonstrate Rails-style POST endpoint with JSON body
+  endpoint(
+    POST('/greetings')
+      .summary('Create a custom greeting')
+      .description('Create a personalized greeting message')
+      .tags('Greetings')
+      .json_body(T.hash({
+        'name' => T.string(min_length: 1),
+        'greeting_style' => T.optional(T.string(enum: %w[formal casual friendly professional]))
+      }))
+      .created(T.hash({
+        'id' => T.integer,
+        'message' => T.string,
+        'style' => T.string,
+        'created_at' => T.string
+      }))
+      .bad_request(T.hash({
+        'error' => T.string,
+        'details' => T.array(T.string)
+      }))
+      .build
+  ) do |inputs|
+    body = inputs[:body]
+    name = body['name']
+    style = body['greeting_style'] || 'friendly'
+    
+    # Validation
+    errors = []
+    errors << 'Name cannot be empty' if name.nil? || name.strip.empty?
+    
+    if errors.any?
+      # Return validation error
+      { error: 'Validation failed', details: errors, _status: 400 }
+    else
+      # Style-based greetings
+      greetings = {
+        'formal' => "Good day, #{name}. It is a pleasure to make your acquaintance.",
+        'casual' => "Hey #{name}! What's up?",
+        'friendly' => "Hello there, #{name}! Hope you're having a great day!",
+        'professional' => "Hello #{name}, welcome to our platform."
+      }
+
+      # Simulate database save with incremental ID
+      greeting_id = rand(1000..9999)
+      
+      # Return created response
+      {
+        id: greeting_id,
+        message: greetings[style],
+        style: style,
+        created_at: Time.now.iso8601,
+        _status: 201
+      }
+    end
+  end
+
+  # Health check endpoint (will be auto-generated in future versions)
+  endpoint(
+    GET('/health')
+      .summary('Health check')
+      .description('Check if the Rails API is running')
+      .tags('System')
+      .ok(T.hash({
+        'status' => T.string,
+        'timestamp' => T.string,
+        'framework' => T.string,
+        'ruby_version' => T.string
+      }))
+      .build
+  ) do |inputs|
+    # Return health status data
+    {
+      status: 'healthy',
+      timestamp: Time.now.iso8601,
+      framework: "Rails #{Rails.version rescue 'Unknown'} + RapiTapir",
+      ruby_version: RUBY_VERSION
+    }
+  end
+
+  # Custom action demonstrating Rails conventions
+  def welcome
+    render json: {
+      message: 'Welcome to RapiTapir with Rails!',
+      documentation: 'Visit /docs for interactive API documentation',
+      examples: {
+        hello: '/hello?name=YourName',
+        greet: '/greet/spanish',
+        health: '/health'
+      }
+    }
+  end
+
+  private
+
+  # Rails-style before_action can still be used
+  # before_action :log_request, only: [:hello, :greet]
+
+  def log_request
+    Rails.logger.info "RapiTapir request: #{request.method} #{request.path}"
+  end
+end

data/examples/rails/hello_world_routes.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Example routes configuration for Hello World Rails API
+# Place this in your config/routes.rb file
+
+Rails.application.routes.draw do
+  # Option 1: Auto-generate routes from RapiTapir endpoints (Recommended)
+  rapitapir_routes_for HelloWorldController
+  
+  # This will automatically generate:
+  # GET  /hello                  hello_world#hello  
+  # GET  /greet/:language        hello_world#greet
+  # POST /greetings              hello_world#greetings
+  # GET  /health                 hello_world#health
+
+  # Option 2: Manual routes (if you prefer explicit control)
+  # get '/hello', to: 'hello_world#hello'
+  # get '/greet/:language', to: 'hello_world#greet'
+  # post '/greetings', to: 'hello_world#create'
+  # get '/health', to: 'hello_world#health'
+  
+  # Welcome page (custom action not defined by RapiTapir)
+  root 'hello_world#welcome'
+  
+  # Future: Auto-generated documentation endpoints
+  # get '/docs', to: 'rapitapir_docs#index'
+  # get '/openapi.json', to: 'rapitapir_docs#openapi'
+end