rapitapir 0.1.1 → 2.0.0

data/examples/rails/traditional_app/app/controllers/api/v1/users_controller.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+class Api::V1::UsersController < ApplicationController
+  rapitapir do
+    # User type definitions
+    user_type = T.hash(
+      id: T.integer,
+      email: T.string,
+      name: T.string,
+      bio: T.string.optional,
+      avatar_url: T.string.optional,
+      created_at: T.string,
+      updated_at: T.string,
+      posts_count: T.integer
+    )
+    
+    create_user_type = T.hash(
+      email: T.string,
+      name: T.string,
+      bio: T.string.optional,
+      password: T.string
+    )
+    
+    update_user_type = T.hash(
+      email: T.string.optional,
+      name: T.string.optional,
+      bio: T.string.optional
+    )
+    
+    # List users with search and pagination
+    GET('/api/v1/users')
+      .in(query(:search, T.string.optional))
+      .in(query(:page, T.integer.default(1)))
+      .in(query(:per_page, T.integer.default(20)))
+      .in(query(:sort, T.enum(['name', 'email', 'created_at']).default('created_at')))
+      .in(query(:order, T.enum(['asc', 'desc']).default('desc')))
+      .out(json_body(
+        users: T.array(user_type),
+        pagination: T.hash(
+          page: T.integer,
+          per_page: T.integer,
+          total: T.integer,
+          total_pages: T.integer,
+          has_next: T.boolean,
+          has_prev: T.boolean
+        )
+      ))
+      .summary("List users")
+      .description("Get a paginated list of users with optional search")
+      .tag("Users")
+    
+    # Get user by ID
+    GET('/api/v1/users/:id')
+      .in(path(:id, T.integer))
+      .out(json_body(user: user_type))
+      .summary("Get user")
+      .description("Get a specific user by ID")
+      .tag("Users")
+    
+    # Create new user
+    POST('/api/v1/users')
+      .in(json_body(create_user_type))
+      .out(json_body(user: user_type), 201)
+      .summary("Create user")
+      .description("Create a new user account")
+      .tag("Users")
+    
+    # Update user
+    PUT('/api/v1/users/:id')
+      .in(path(:id, T.integer))
+      .in(json_body(update_user_type))
+      .out(json_body(user: user_type))
+      .summary("Update user")
+      .description("Update an existing user")
+      .tag("Users")
+    
+    # Delete user
+    DELETE('/api/v1/users/:id')
+      .in(path(:id, T.integer))
+      .out(json_body(message: T.string))
+      .summary("Delete user")
+      .description("Delete a user account")
+      .tag("Users")
+    
+    # Get user's posts
+    GET('/api/v1/users/:id/posts')
+      .in(path(:id, T.integer))
+      .in(query(:published, T.boolean.optional))
+      .in(query(:page, T.integer.default(1)))
+      .out(json_body(
+        posts: T.array(T.hash(
+          id: T.integer,
+          title: T.string,
+          excerpt: T.string,
+          published: T.boolean,
+          created_at: T.string
+        )),
+        pagination: T.hash(
+          page: T.integer,
+          total: T.integer,
+          total_pages: T.integer
+        )
+      ))
+      .summary("Get user posts")
+      .description("Get all posts by a specific user")
+      .tag("Users")
+  end
+  
+  def list_users
+    users_scope = User.includes(:posts)
+    
+    # Apply search filter
+    if inputs[:search].present?
+      search_term = "%#{inputs[:search]}%"
+      users_scope = users_scope.where(
+        "name ILIKE ? OR email ILIKE ?", search_term, search_term
+      )
+    end
+    
+    # Apply sorting
+    order_clause = "#{inputs[:sort]} #{inputs[:order]}"
+    users_scope = users_scope.order(order_clause)
+    
+    # Pagination
+    page = inputs[:page]
+    per_page = [inputs[:per_page], 100].min # Cap at 100
+    
+    users = users_scope.page(page).per(per_page)
+    
+    {
+      users: users.map { |user| serialize_user(user) },
+      pagination: pagination_metadata(users_scope, page, per_page)
+    }
+  end
+  
+  def get_user
+    user = User.includes(:posts).find_by(id: inputs[:id])
+    return render_error("User not found", 404) unless user
+    
+    { user: serialize_user(user) }
+  end
+  
+  def create_user
+    user = User.new(user_create_params)
+    
+    if user.save
+      render json: { user: serialize_user(user) }, status: 201
+    else
+      render_error("Validation failed", 422, errors: user.errors.full_messages)
+    end
+  end
+  
+  def update_user
+    user = User.find_by(id: inputs[:id])
+    return render_error("User not found", 404) unless user
+    
+    if user.update(user_update_params)
+      { user: serialize_user(user) }
+    else
+      render_error("Validation failed", 422, errors: user.errors.full_messages)
+    end
+  end
+  
+  def delete_user
+    user = User.find_by(id: inputs[:id])
+    return render_error("User not found", 404) unless user
+    
+    user.destroy
+    { message: "User deleted successfully" }
+  end
+  
+  def get_user_posts
+    user = User.find_by(id: inputs[:id])
+    return render_error("User not found", 404) unless user
+    
+    posts_scope = user.posts
+    posts_scope = posts_scope.where(published: inputs[:published]) if inputs.key?(:published)
+    
+    page = inputs[:page]
+    posts = posts_scope.page(page).per(10)
+    
+    {
+      posts: posts.map { |post| serialize_post_summary(post) },
+      pagination: pagination_metadata(posts_scope, page, 10)
+    }
+  end
+  
+  private
+  
+  def user_create_params
+    inputs.slice(:email, :name, :bio, :password)
+  end
+  
+  def user_update_params
+    inputs.slice(:email, :name, :bio).compact
+  end
+  
+  def serialize_user(user)
+    {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      bio: user.bio,
+      avatar_url: user.avatar_url,
+      created_at: user.created_at.iso8601,
+      updated_at: user.updated_at.iso8601,
+      posts_count: user.posts.count
+    }
+  end
+  
+  def serialize_post_summary(post)
+    {
+      id: post.id,
+      title: post.title,
+      excerpt: post.content.truncate(200),
+      published: post.published,
+      created_at: post.created_at.iso8601
+    }
+  end
+end

data/examples/rails/traditional_app/app/controllers/application_controller.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class ApplicationController < RapiTapir::Server::Rails::ControllerBase
+  # Global configuration for all controllers
+  rapitapir do
+    # Enable development features (automatic docs, etc.)
+    development_defaults! if Rails.env.development?
+    
+    # Global error handling
+    error_out(json_body(error: T.string, details: T.string.optional), 500)
+    error_out(json_body(error: T.string), 401)
+    error_out(json_body(error: T.string), 403)
+    error_out(json_body(error: T.string), 404)
+    error_out(json_body(error: T.string, errors: T.array(T.string).optional), 422)
+    
+    # Health check endpoint - no separate controller needed!
+    GET('/health')
+      .out(json_body(
+        status: T.string,
+        timestamp: T.string,
+        version: T.string,
+        environment: T.string,
+        database: T.string,
+        services: T.hash(redis: T.string)
+      ))
+      .summary("Health check")
+      .description("Check API and service health")
+      .tag("System")
+  end
+  
+  def health_check
+    {
+      status: 'ok',
+      timestamp: Time.current.iso8601,
+      version: '1.0.0',
+      environment: Rails.env,
+      database: database_status,
+      services: {
+        redis: redis_status
+      }
+    }
+  end
+  
+  protected
+  
+  # Helper method for standardized error responses
+  def render_error(message, status, details: nil, errors: nil)
+    payload = { error: message }
+    payload[:details] = details if details
+    payload[:errors] = errors if errors
+    
+    render json: payload, status: status
+  end
+  
+  # Helper for pagination metadata
+  def pagination_metadata(collection, page, per_page)
+    total = collection.respond_to?(:count) ? collection.count : collection.size
+    {
+      page: page,
+      per_page: per_page,
+      total: total,
+      total_pages: (total.to_f / per_page).ceil,
+      has_next: page < (total.to_f / per_page).ceil,
+      has_prev: page > 1
+    }
+  end
+  
+  private
+  
+  def database_status
+    ActiveRecord::Base.connection.execute('SELECT 1')
+    'connected'
+  rescue => e
+    Rails.logger.error "Database check failed: #{e.message}"
+    'disconnected'
+  end
+  
+  def redis_status
+    # Example Redis check - uncomment if using Redis
+    # Redis.current.ping == 'PONG' ? 'connected' : 'disconnected'
+    'not_configured'
+  rescue => e
+    Rails.logger.error "Redis check failed: #{e.message}"
+    'disconnected'
+  end
+end

data/examples/rails/traditional_app/app/controllers/application_controller_simplified.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+class ApplicationController < RapiTapir::Server::Rails::ControllerBase
+  include RapiTapir::Server::Rails::DocumentationHelpers
+  
+  rapitapir do
+    # Enable development features (automatic docs, etc.)
+    development_defaults! if Rails.env.development?
+    
+    # Global error handling
+    error_out(json_body(error: T.string, details: T.string.optional), 500)
+    error_out(json_body(error: T.string), 401)
+    error_out(json_body(error: T.string), 403)
+    error_out(json_body(error: T.string), 404)
+    error_out(json_body(error: T.string, errors: T.array(T.string).optional), 422)
+    
+    # Health check endpoint - no separate controller needed!
+    GET('/health')
+      .out(json_body(
+        status: T.string,
+        timestamp: T.string,
+        version: T.string,
+        environment: T.string,
+        database: T.string,
+        services: T.hash(redis: T.string)
+      ))
+      .summary("Health check")
+      .description("Check API and service health")
+      .tag("System")
+  end
+  
+  def health_check
+    {
+      status: 'ok',
+      timestamp: Time.current.iso8601,
+      version: '1.0.0',
+      environment: Rails.env,
+      database: database_status,
+      services: {
+        redis: redis_status
+      }
+    }
+  end
+  
+  protected
+  
+  # Helper method for standardized error responses
+  def render_error(message, status, details: nil, errors: nil)
+    payload = { error: message }
+    payload[:details] = details if details
+    payload[:errors] = errors if errors
+    
+    render json: payload, status: status
+  end
+  
+  # Helper for pagination metadata
+  def pagination_metadata(collection, page, per_page)
+    total = collection.respond_to?(:count) ? collection.count : collection.size
+    {
+      page: page,
+      per_page: per_page,
+      total: total,
+      total_pages: (total.to_f / per_page).ceil,
+      has_next: page < (total.to_f / per_page).ceil,
+      has_prev: page > 1
+    }
+  end
+  
+  private
+  
+  def database_status
+    ActiveRecord::Base.connection.execute('SELECT 1')
+    'connected'
+  rescue => e
+    Rails.logger.error "Database check failed: #{e.message}"
+    'disconnected'
+  end
+  
+  def redis_status
+    # Example Redis check - uncomment if using Redis
+    # Redis.current.ping == 'PONG' ? 'connected' : 'disconnected'
+    'not_configured'
+  rescue => e
+    Rails.logger.error "Redis check failed: #{e.message}"
+    'disconnected'
+  end
+end

data/examples/rails/traditional_app/app/controllers/documentation_controller.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+class DocumentationController < ApplicationController
+  skip_before_action :verify_authenticity_token, if: -> { request.format.json? }
+  
+  def swagger_ui
+    render html: swagger_ui_html.html_safe
+  end
+  
+  def openapi_spec
+    render json: generate_openapi_spec
+  end
+  
+  def redoc
+    render html: redoc_html.html_safe
+  end
+  
+  private
+  
+  def swagger_ui_html
+    <<~HTML
+      <!DOCTYPE html>
+      <html>
+      <head>
+        <title>#{Rails.application.class.name.split('::').first} API Documentation</title>
+        <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@4.15.5/swagger-ui.css" />
+        <style>
+          html { box-sizing: border-box; overflow: -moz-scrollbars-vertical; overflow-y: scroll; }
+          *, *:before, *:after { box-sizing: inherit; }
+          body { margin:0; background: #fafafa; }
+        </style>
+      </head>
+      <body>
+        <div id="swagger-ui"></div>
+        <script src="https://unpkg.com/swagger-ui-dist@4.15.5/swagger-ui-bundle.js"></script>
+        <script src="https://unpkg.com/swagger-ui-dist@4.15.5/swagger-ui-standalone-preset.js"></script>
+        <script>
+          window.onload = function() {
+            const ui = SwaggerUIBundle({
+              url: '/openapi.json',
+              dom_id: '#swagger-ui',
+              deepLinking: true,
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset
+              ],
+              plugins: [
+                SwaggerUIBundle.plugins.DownloadUrl
+              ],
+              layout: "StandaloneLayout"
+            });
+          };
+        </script>
+      </body>
+      </html>
+    HTML
+  end
+  
+  def redoc_html
+    <<~HTML
+      <!DOCTYPE html>
+      <html>
+      <head>
+        <title>#{Rails.application.class.name.split('::').first} API Documentation</title>
+        <meta charset="utf-8"/>
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+        <style>
+          body { margin: 0; padding: 0; }
+        </style>
+      </head>
+      <body>
+        <redoc spec-url='/openapi.json'></redoc>
+        <script src="https://cdn.jsdelivr.net/npm/redoc@2.0.0/bundles/redoc.standalone.js"></script>
+      </body>
+      </html>
+    HTML
+  end
+  
+  def generate_openapi_spec
+    {
+      openapi: "3.0.3",
+      info: {
+        title: "#{Rails.application.class.name.split('::').first} API",
+        version: "1.0.0",
+        description: "API documentation generated by RapiTapir",
+        contact: {
+          name: "API Support",
+          email: "support@example.com"
+        }
+      },
+      servers: [
+        {
+          url: "#{request.protocol}#{request.host_with_port}",
+          description: "#{Rails.env.capitalize} server"
+        }
+      ],
+      paths: generate_paths,
+      components: {
+        securitySchemes: {
+          bearerAuth: {
+            type: "http",
+            scheme: "bearer",
+            bearerFormat: "JWT"
+          }
+        }
+      }
+    }
+  end
+  
+  def generate_paths
+    paths = {}
+    
+    # Get all RapiTapir controllers
+    rapitapir_controllers = [
+      Api::V1::UsersController,
+      Api::V1::PostsController
+    ]
+    
+    rapitapir_controllers.each do |controller|
+      next unless controller.respond_to?(:endpoints)
+      
+      controller.endpoints.each do |endpoint|
+        path_key = endpoint.path.gsub(/:(\w+)/, '{\1}')
+        method = endpoint.method.downcase
+        
+        paths[path_key] ||= {}
+        paths[path_key][method] = {
+          summary: endpoint.summary || "#{method.upcase} #{path_key}",
+          description: endpoint.description || "",
+          tags: endpoint.tags || [controller.name.demodulize.gsub('Controller', '')],
+          operationId: "#{method}_#{path_key.gsub(/[\/{}]/, '_').gsub(/_+/, '_').gsub(/^_|_$/, '')}",
+          responses: {
+            "200" => {
+              description: "Success"
+            }
+          }
+        }
+        
+        # Add authentication if required
+        if endpoint.inputs.any? { |input| input.name == :authorization }
+          paths[path_key][method][:security] = [{ bearerAuth: [] }]
+        end
+      end
+    end
+    
+    paths
+  end
+end

data/examples/rails/traditional_app/app/controllers/health_controller.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class HealthController < ApplicationController
+  skip_before_action :verify_authenticity_token
+  
+  def check
+    render json: {
+      status: 'ok',
+      timestamp: Time.current.iso8601,
+      version: '1.0.0',
+      environment: Rails.env,
+      database: database_status,
+      services: services_status
+    }
+  end
+  
+  private
+  
+  def database_status
+    ActiveRecord::Base.connection.execute('SELECT 1')
+    'connected'
+  rescue => e
+    Rails.logger.error "Database check failed: #{e.message}"
+    'disconnected'
+  end
+  
+  def services_status
+    {
+      redis: redis_status,
+      # Add other service checks here
+    }
+  end
+  
+  def redis_status
+    # Example Redis check - uncomment if using Redis
+    # Redis.current.ping == 'PONG' ? 'connected' : 'disconnected'
+    'not_configured'
+  rescue => e
+    Rails.logger.error "Redis check failed: #{e.message}"
+    'disconnected'
+  end
+end

data/examples/rails/traditional_app/config/routes.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  # Health check (from ApplicationController)
+  rapitapir_routes_for ApplicationController
+  
+  # API v1 routes - RapiTapir auto-generates routes from endpoint definitions
+  namespace :api do
+    namespace :v1 do
+      rapitapir_routes_for 'Api::V1::UsersController'
+      rapitapir_routes_for 'Api::V1::PostsController'
+    end
+  end
+  
+  # Documentation routes (automatically added by development_defaults! in development)
+  # Available at:
+  # - GET /docs          -> Swagger UI
+  # - GET /openapi.json  -> OpenAPI 3.0 specification
+  # - GET /redoc         -> ReDoc alternative UI (if enabled)
+  
+  # Catch-all for unmatched routes
+  match '*path', to: proc { |env|
+    [404, { 'Content-Type' => 'application/json' }, [{ error: 'Route not found' }.to_json]]
+  }, via: :all
+end

data/examples/rails/traditional_app/config/routes_best_practice.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Simplified Rails application using RapiTapir best practices
+# No separate health or documentation controllers needed!
+
+Rails.application.routes.draw do
+  # Health check and docs are handled by RapiTapir automatically
+  rapitapir_routes_for ApplicationController
+  
+  # API endpoints
+  namespace :api do
+    namespace :v1 do
+      rapitapir_routes_for 'Api::V1::UsersController'
+      rapitapir_routes_for 'Api::V1::PostsController'
+    end
+  end
+  
+  # RapiTapir provides documentation routes automatically in development
+  if Rails.env.development?
+    # These are automatically added by development_defaults!
+    # /docs -> Swagger UI
+    # /openapi.json -> OpenAPI spec
+    # /redoc -> ReDoc alternative UI
+  end
+end

data/examples/rails/traditional_app/config/routes_simplified.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  # Use RapiTapir's built-in route generation for all controllers
+  rapitapir_routes_for ApplicationController  # This includes /health
+  
+  # API v1 routes
+  namespace :api do
+    namespace :v1 do
+      rapitapir_routes_for 'Api::V1::UsersController'
+      rapitapir_routes_for 'Api::V1::PostsController'
+    end
+  end
+  
+  # Documentation routes using RapiTapir's built-in helpers
+  if Rails.env.development?
+    # These use the DocumentationHelpers module that's already included
+    get '/docs', to: proc { |env|
+      request = ActionDispatch::Request.new(env)
+      html = ApplicationController.new.send(:generate_swagger_ui_html)
+      [200, { 'Content-Type' => 'text/html' }, [html]]
+    }
+    
+    get '/openapi.json', to: proc { |env|
+      request = ActionDispatch::Request.new(env)
+      controllers = [ApplicationController, Api::V1::UsersController, Api::V1::PostsController]
+      spec = ApplicationController.new.send(:generate_openapi_spec_for_controllers, controllers)
+      [200, { 'Content-Type' => 'application/json' }, [JSON.pretty_generate(spec)]]
+    }
+  end
+  
+  # Catch-all for unmatched routes
+  match '*path', to: proc { |env|
+    [404, { 'Content-Type' => 'application/json' }, [{ error: 'Route not found' }.to_json]]
+  }, via: :all
+end