rapitapir 0.1.2 → 2.0.0

data/examples/rails/test_rails_integration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Test script to verify Rails integration loads properly with correct order
+
+# First, simulate Rails being loaded (this is what Rails apps do)
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'rails', '~> 8.0'
+  gem 'activesupport'
+end
+
+# Load Rails and ActiveSupport first (this is crucial!)
+require 'rails/all'
+
+# NOW load RapiTapir (this is the correct order)
+require_relative '../../lib/rapitapir'
+
+puts "Testing RapiTapir Rails integration loading..."
+
+begin
+  # Try to access the ControllerBase class
+  controller_base = RapiTapir::Server::Rails::ControllerBase
+  puts "✅ RapiTapir::Server::Rails::ControllerBase loaded successfully"
+  
+  # Test that it's a class
+  if controller_base.is_a?(Class)
+    puts "✅ ControllerBase is a proper class"
+  else
+    puts "❌ ControllerBase is not a class: #{controller_base.class}"
+  end
+  
+  # Test other components
+  config = RapiTapir::Server::Rails::Configuration
+  puts "✅ RapiTapir::Server::Rails::Configuration loaded"
+  
+  routes = RapiTapir::Server::Rails::Routes
+  puts "✅ RapiTapir::Server::Rails::Routes loaded"
+  
+  puts "\n🎉 All Rails integration components loaded successfully!"
+  
+rescue NameError => e
+  puts "❌ Error loading Rails integration: #{e.message}"
+  puts "   This means there's still an issue with the loading order"
+  exit 1
+rescue => e
+  puts "❌ Unexpected error: #{e.message}"
+  puts "   #{e.backtrace.first(3).join("\n   ")}"
+  exit 1
+end
+
+puts "\n✅ Rails integration test passed!"
+puts "✅ The correct loading order is: Rails first, then RapiTapir"

data/examples/rails/traditional_app/Gemfile

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Gemfile for a traditional Rails app with RapiTapir
+source 'https://rubygems.org'
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+ruby '3.2.0'
+
+# Rails framework
+gem 'rails', '~> 8.0.0'
+
+# Database
+gem 'sqlite3', '~> 1.4'
+
+# Web server
+gem 'puma', '~> 6.0'
+
+# Reduces boot times through caching; required in config/boot.rb
+gem 'bootsnap', '>= 1.4.4', require: false
+
+# RapiTapir for API definitions
+# In a real app, you'd add this to your Gemfile:
+# gem 'rapitapir', '~> 1.0'
+
+# For this example, we'll use a local path
+gem 'rapitapir', path: '../../../'
+
+group :development, :test do
+  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
+  gem 'rspec-rails'
+  gem 'factory_bot_rails'
+end
+
+group :development do
+  gem 'listen', '~> 3.3'
+  gem 'spring'
+end

data/examples/rails/traditional_app/README.md

@@ -0,0 +1,265 @@
+# Traditional Rails Application with RapiTapir
+
+This example demonstrates how to structure a **real Rails application** using RapiTapir following Rails conventions and best practices.
+
+## 📁 Clean Structure
+
+```
+traditional_app/
+├── Gemfile                                   # Dependencies
+├── README.md                                 # This file
+├── app/
+│   └── controllers/
+│       ├── application_controller.rb        # Base controller with health check
+│       └── api/
+│           └── v1/
+│               ├── users_controller.rb      # User API endpoints
+│               └── posts_controller.rb      # Post API endpoints
+└── config/
+    └── routes.rb                            # Clean routing with rapitapir_routes_for
+```
+
+## 🎯 Key Features
+
+### ✅ **Simplified Architecture**
+- **No separate health controller** - health check is an endpoint in ApplicationController
+- **No separate documentation controller** - uses RapiTapir's built-in `DocumentationHelpers`
+- **Auto-generated routes** - `rapitapir_routes_for` creates routes from endpoint definitions
+- **Auto-generated docs** - `development_defaults!` enables `/docs` and `/openapi.json`
+
+### ✅ **Rails Best Practices**
+- **Namespaced APIs** - `/api/v1/` structure
+- **Global error handling** - Defined once in ApplicationController
+- **Standard Rails patterns** - Filters, rescue handlers, etc.
+- **Environment-aware** - Documentation only in development
+
+### ✅ **Production Ready**
+- **Comprehensive error responses** - 401, 403, 404, 422, 500
+- **Type safety** - All inputs/outputs defined and validated
+- **Health monitoring** - Database and service status checks
+- **API documentation** - Always up-to-date with code
+
+## 🚀 Running the Application
+
+### Option 1: Runnable Demo (Easiest)
+
+For a quick demo, use the standalone runnable version:
+
+```bash
+# From the examples/rails directory
+ruby traditional_app_runnable.rb
+
+# Visit the endpoints:
+# - http://localhost:3000/docs (Swagger UI)
+# - http://localhost:3000/health (Health check)
+# - http://localhost:3000/api/v1/users (Users API)
+# - http://localhost:3000/api/v1/posts (Posts API)
+```
+
+This single file demonstrates the complete traditional Rails app structure.
+
+### Option 2: Full Rails Application
+
+To create a complete Rails application using this structure:
+
+#### 1. Create New Rails App
+```bash
+rails new my_api_app --api
+cd my_api_app
+```
+
+#### 2. Add RapiTapir to Gemfile
+```ruby
+gem 'rapitapir', '~> 1.0'
+```
+
+#### 3. Copy the Controller Structure
+Copy the controllers from this example:
+- `app/controllers/application_controller.rb`
+- `app/controllers/api/v1/users_controller.rb`
+- `app/controllers/api/v1/posts_controller.rb`
+
+#### 4. Update Routes
+Copy the routes configuration from `config/routes.rb`
+
+#### 5. Run Standard Rails Commands
+```bash
+bundle install
+rails db:create
+rails db:migrate
+rails server
+```
+
+## 📋 Available Endpoints
+
+### System
+- `GET /health` - Health check with database and service status
+
+### Users API (`/api/v1/users`)
+- `GET /api/v1/users` - List users (with search, pagination, sorting)
+- `GET /api/v1/users/:id` - Get specific user
+- `POST /api/v1/users` - Create new user
+- `PUT /api/v1/users/:id` - Update user
+- `DELETE /api/v1/users/:id` - Delete user
+- `GET /api/v1/users/:id/posts` - Get user's posts
+
+### Posts API (`/api/v1/posts`)
+- `GET /api/v1/posts` - List posts (with filtering)
+- `GET /api/v1/posts/:id` - Get specific post
+- `POST /api/v1/posts` - Create new post (requires auth)
+- `PUT /api/v1/posts/:id` - Update post (requires auth)
+- `DELETE /api/v1/posts/:id` - Delete post (requires auth)
+- `PATCH /api/v1/posts/:id/publish` - Toggle publish status (requires auth)
+
+## 🔧 Key Implementation Details
+
+### ApplicationController Pattern
+```ruby
+class ApplicationController < RapiTapir::Server::Rails::ControllerBase
+  rapitapir do
+    development_defaults! if Rails.env.development?
+    
+    # Global error responses
+    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
+    GET('/health')
+      .out(json_body(status: T.string, timestamp: T.string, ...))
+  end
+end
+```
+
+### Auto-Generated Routes
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  rapitapir_routes_for ApplicationController  # Generates /health
+  
+  namespace :api do
+    namespace :v1 do
+      rapitapir_routes_for 'Api::V1::UsersController'  # Auto-generates all user routes
+      rapitapir_routes_for 'Api::V1::PostsController'  # Auto-generates all post routes
+    end
+  end
+end
+```
+
+### Type-Safe Controllers
+```ruby
+class Api::V1::UsersController < ApplicationController
+  rapitapir do
+    GET('/api/v1/users')
+      .in(query(:page, T.integer.default(1)))
+      .in(query(:search, T.string.optional))
+      .out(json_body(users: T.array(user_type), pagination: pagination_type))
+  end
+  
+  def list_users
+    # inputs[:page] and inputs[:search] are automatically validated
+    users = User.where(conditions).page(inputs[:page])
+    { users: users.map(&method(:serialize_user)) }
+  end
+end
+```
+
+## 🆚 Comparison with Standard Rails
+
+### Before (Standard Rails)
+```ruby
+# Multiple controllers for health/docs
+class HealthController < ApplicationController
+  def check
+    # Custom health check logic
+  end
+end
+
+class DocumentationController < ApplicationController  
+  def swagger_ui
+    # Custom Swagger UI rendering
+  end
+end
+
+# Manual route definitions
+Rails.application.routes.draw do
+  get '/health', to: 'health#check'
+  get '/docs', to: 'documentation#swagger_ui'
+  
+  resources :users  # Generic CRUD, no type safety
+end
+
+# Manual parameter handling
+class UsersController < ApplicationController
+  def index
+    page = params[:page]&.to_i || 1  # Manual validation
+    users = User.page(page)
+    render json: { users: users }    # No output type safety
+  end
+end
+```
+
+### After (RapiTapir)
+```ruby
+# Single ApplicationController with health endpoint
+class ApplicationController < RapiTapir::Server::Rails::ControllerBase
+  rapitapir do
+    development_defaults!  # Auto docs
+    GET('/health').out(json_body(...))  # Type-safe health endpoint
+  end
+end
+
+# Auto-generated routes
+Rails.application.routes.draw do
+  rapitapir_routes_for ApplicationController  # Health + docs
+  rapitapir_routes_for 'Api::V1::UsersController'  # All user routes
+end
+
+# Type-safe controllers
+class Api::V1::UsersController < ApplicationController
+  rapitapir do
+    GET('/api/v1/users')
+      .in(query(:page, T.integer.default(1)))  # Auto validation
+      .out(json_body(users: T.array(user_type)))  # Type-safe output
+  end
+  
+  def list_users
+    users = User.page(inputs[:page])  # inputs guaranteed valid
+    { users: users.map(&method(:serialize_user)) }  # Return data, not render
+  end
+end
+```
+
+## 🏗️ Benefits for Real Rails Apps
+
+1. **Fewer Files**: No separate health/docs controllers
+2. **Less Boilerplate**: Auto-generated routes and validation
+3. **Type Safety**: Input/output validation with clear error messages
+4. **Always Up-to-date Docs**: Documentation reflects actual code
+5. **Rails Ecosystem**: Works with existing gems, middleware, and patterns
+6. **Testing**: Standard Rails testing patterns work perfectly
+7. **Performance**: No overhead, just cleaner organization
+
+## 🧪 Testing Example
+
+```ruby
+# spec/controllers/api/v1/users_controller_spec.rb
+RSpec.describe Api::V1::UsersController, type: :controller do
+  describe 'GET #list_users' do
+    it 'validates page parameter' do
+      get :list_users, params: { page: "invalid" }
+      expect(response).to have_http_status(:unprocessable_entity)
+    end
+    
+    it 'returns paginated users' do
+      create_list(:user, 15)
+      get :list_users, params: { page: 2 }
+      
+      expect(response).to have_http_status(:ok)
+      expect(json_response[:users]).to be_an(Array)
+      expect(json_response[:pagination][:page]).to eq(2)
+    end
+  end
+end
+```
+
+This example shows how RapiTapir makes Rails APIs cleaner, safer, and more maintainable while preserving all the Rails patterns you know and love! 🎉

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+class Api::V1::PostsController < ApplicationController
+  rapitapir do
+    # Type definitions
+    post_type = T.hash(
+      id: T.integer,
+      title: T.string,
+      content: T.string,
+      excerpt: T.string,
+      published: T.boolean,
+      tags: T.array(T.string),
+      user: T.hash(
+        id: T.integer,
+        name: T.string,
+        email: T.string
+      ),
+      comments_count: T.integer,
+      created_at: T.string,
+      updated_at: T.string
+    )
+    
+    # List posts with filtering
+    GET('/api/v1/posts')
+      .in(query(:published, T.boolean.optional))
+      .in(query(:tag, T.string.optional))
+      .in(query(:user_id, T.integer.optional))
+      .in(query(:search, T.string.optional))
+      .in(query(:page, T.integer.default(1)))
+      .in(query(:per_page, T.integer.default(10)))
+      .out(json_body(
+        posts: T.array(post_type),
+        pagination: T.hash(
+          page: T.integer,
+          per_page: T.integer,
+          total: T.integer,
+          total_pages: T.integer
+        ),
+        filters: T.hash(
+          published: T.boolean.optional,
+          tag: T.string.optional,
+          user_id: T.integer.optional,
+          search: T.string.optional
+        )
+      ))
+      .summary("List posts")
+      .description("Get posts with filtering and pagination")
+      .tag("Posts")
+    
+    # Get specific post
+    GET('/api/v1/posts/:id')
+      .in(path(:id, T.integer))
+      .in(query(:include_comments, T.boolean.default(false)))
+      .out(json_body(
+        post: post_type,
+        comments: T.array(T.hash(
+          id: T.integer,
+          content: T.string,
+          user: T.hash(id: T.integer, name: T.string),
+          created_at: T.string
+        )).optional
+      ))
+      .summary("Get post")
+      .description("Get a specific post with optional comments")
+      .tag("Posts")
+    
+    # Create post
+    POST('/api/v1/posts')
+      .in(json_body(
+        title: T.string,
+        content: T.string,
+        published: T.boolean.default(false),
+        tags: T.array(T.string).default([])
+      ))
+      .in(header(:authorization, T.string))
+      .out(json_body(post: post_type), 201)
+      .summary("Create post")
+      .description("Create a new blog post")
+      .tag("Posts")
+    
+    # Update post
+    PUT('/api/v1/posts/:id')
+      .in(path(:id, T.integer))
+      .in(json_body(
+        title: T.string.optional,
+        content: T.string.optional,
+        published: T.boolean.optional,
+        tags: T.array(T.string).optional
+      ))
+      .in(header(:authorization, T.string))
+      .out(json_body(post: post_type))
+      .summary("Update post")
+      .description("Update an existing post")
+      .tag("Posts")
+    
+    # Delete post
+    DELETE('/api/v1/posts/:id')
+      .in(path(:id, T.integer))
+      .in(header(:authorization, T.string))
+      .out(json_body(message: T.string))
+      .summary("Delete post")
+      .description("Delete a blog post")
+      .tag("Posts")
+    
+    # Publish/unpublish post
+    PATCH('/api/v1/posts/:id/publish')
+      .in(path(:id, T.integer))
+      .in(json_body(published: T.boolean))
+      .in(header(:authorization, T.string))
+      .out(json_body(post: post_type))
+      .summary("Toggle post publication")
+      .description("Publish or unpublish a post")
+      .tag("Posts")
+  end
+  
+  before_action :authenticate_user!, only: [:create_post, :update_post, :delete_post, :toggle_publish]
+  before_action :authorize_post_owner!, only: [:update_post, :delete_post, :toggle_publish]
+  
+  def list_posts
+    posts_scope = Post.includes(:user, :comments)
+    
+    # Apply filters
+    posts_scope = posts_scope.where(published: inputs[:published]) if inputs.key?(:published)
+    posts_scope = posts_scope.where(user_id: inputs[:user_id]) if inputs[:user_id]
+    posts_scope = posts_scope.joins(:tags).where(tags: { name: inputs[:tag] }) if inputs[:tag]
+    
+    # Search
+    if inputs[:search].present?
+      search_term = "%#{inputs[:search]}%"
+      posts_scope = posts_scope.where(
+        "title ILIKE ? OR content ILIKE ?", search_term, search_term
+      )
+    end
+    
+    # Pagination
+    page = inputs[:page]
+    per_page = inputs[:per_page]
+    posts = posts_scope.order(created_at: :desc).page(page).per(per_page)
+    
+    {
+      posts: posts.map { |post| serialize_post(post) },
+      pagination: pagination_metadata(posts_scope, page, per_page),
+      filters: inputs.slice(:published, :tag, :user_id, :search).compact
+    }
+  end
+  
+  def get_post
+    post = Post.includes(:user, :comments, :tags).find_by(id: inputs[:id])
+    return render_error("Post not found", 404) unless post
+    
+    response = { post: serialize_post(post) }
+    
+    if inputs[:include_comments]
+      response[:comments] = post.comments.includes(:user).map do |comment|
+        {
+          id: comment.id,
+          content: comment.content,
+          user: {
+            id: comment.user.id,
+            name: comment.user.name
+          },
+          created_at: comment.created_at.iso8601
+        }
+      end
+    end
+    
+    response
+  end
+  
+  def create_post
+    post = current_user.posts.build(post_params)
+    
+    if post.save
+      add_tags_to_post(post, inputs[:tags]) if inputs[:tags]
+      render json: { post: serialize_post(post.reload) }, status: 201
+    else
+      render_error("Validation failed", 422, errors: post.errors.full_messages)
+    end
+  end
+  
+  def update_post
+    if @post.update(post_params.compact)
+      add_tags_to_post(@post, inputs[:tags]) if inputs[:tags]
+      { post: serialize_post(@post.reload) }
+    else
+      render_error("Validation failed", 422, errors: @post.errors.full_messages)
+    end
+  end
+  
+  def delete_post
+    @post.destroy
+    { message: "Post deleted successfully" }
+  end
+  
+  def toggle_publish
+    if @post.update(published: inputs[:published])
+      { post: serialize_post(@post) }
+    else
+      render_error("Failed to update post", 422, errors: @post.errors.full_messages)
+    end
+  end
+  
+  private
+  
+  def authenticate_user!
+    token = inputs[:authorization]&.sub(/^Bearer /, '')
+    return render_error("Authorization required", 401) unless token
+    
+    # In a real app, you'd validate the JWT token here
+    @current_user = User.find_by(auth_token: token)
+    return render_error("Invalid token", 401) unless @current_user
+  end
+  
+  def current_user
+    @current_user
+  end
+  
+  def authorize_post_owner!
+    @post = Post.find_by(id: inputs[:id])
+    return render_error("Post not found", 404) unless @post
+    return render_error("Forbidden", 403) unless @post.user == current_user
+  end
+  
+  def post_params
+    inputs.slice(:title, :content, :published)
+  end
+  
+  def add_tags_to_post(post, tag_names)
+    post.tags.clear
+    tag_names.each do |name|
+      tag = Tag.find_or_create_by(name: name.strip.downcase)
+      post.tags << tag unless post.tags.include?(tag)
+    end
+  end
+  
+  def serialize_post(post)
+    {
+      id: post.id,
+      title: post.title,
+      content: post.content,
+      excerpt: post.content.truncate(200),
+      published: post.published,
+      tags: post.tags.pluck(:name),
+      user: {
+        id: post.user.id,
+        name: post.user.name,
+        email: post.user.email
+      },
+      comments_count: post.comments.count,
+      created_at: post.created_at.iso8601,
+      updated_at: post.updated_at.iso8601
+    }
+  end
+end