rapitapir 0.1.1 → 2.0.0

data/docs/endpoint-definition.md

@@ -1,211 +1,618 @@
-# RapiTapir Endpoint DSL Reference
+# RapiTapir Endpoint Definition Guide
 
-This document describes the RapiTapir DSL for defining HTTP API endpoints in Ruby with type safety and validation.
+This comprehensive guide covers the RapiTapir DSL for defining HTTP API endpoints with type safety, validation, and automatic documentation generation.
 
-## Basic Usage
+## Table of Contents
+
+- [Overview](#overview)
+- [HTTP Verb Methods](#http-verb-methods)
+- [Input Definitions](#input-definitions)
+- [Output Definitions](#output-definitions)
+- [Metadata and Documentation](#metadata-and-documentation)
+- [Advanced Features](#advanced-features)
+- [Type System Integration](#type-system-integration)
+- [Complete Examples](#complete-examples)
+
+## Overview
+
+RapiTapir provides a fluent, chainable DSL for defining HTTP endpoints. The modern DSL uses HTTP verb methods (`GET()`, `POST()`, etc.) combined with the global `T` shortcut for clean, readable endpoint definitions.
+
+### Basic Structure
 
 ```ruby
-require 'rapitapir'
+endpoint(
+  HTTP_VERB('/path')
+    .input_definitions()     # Query params, path params, headers, body
+    .output_definitions()    # Success and error responses
+    .metadata()             # Summary, description, tags, etc.
+    .build
+) do |inputs|
+  # Your endpoint implementation
+end
+```
+
+## HTTP Verb Methods
 
-endpoint = RapiTapir.get('/hello')
-  .in(RapiTapir.query(:name, :string))
-  .out(RapiTapir.json_body(message: :string))
+All standard HTTP methods are available as chainable builders:
+
+```ruby
+# All HTTP verbs supported
+GET('/users')          # Retrieve resources
+POST('/users')         # Create resources  
+PUT('/users/:id')      # Update/replace resources
+PATCH('/users/:id')    # Partial updates
+DELETE('/users/:id')   # Delete resources
+OPTIONS('/users')      # CORS preflight
+HEAD('/users')         # Headers only
 ```
 
-## HTTP Methods
+### Path Parameters
 
-RapiTapir supports all standard HTTP methods:
+Define path parameters directly in the URL pattern:
 
 ```ruby
-RapiTapir.get('/users')      # GET endpoint
-RapiTapir.post('/users')     # POST endpoint
-RapiTapir.put('/users/:id')  # PUT endpoint
-RapiTapir.patch('/users/:id') # PATCH endpoint
-RapiTapir.delete('/users/:id') # DELETE endpoint
-RapiTapir.options('/users')  # OPTIONS endpoint
-RapiTapir.head('/users')     # HEAD endpoint
+GET('/users/:id')              # Single parameter
+GET('/users/:id/posts/:post_id') # Multiple parameters
+GET('/files/*path')            # Splat parameters
 ```
 
-## Input DSL Helpers
+## Input Definitions
 
 ### Query Parameters
+
 ```ruby
-.in(query(:name, :string))
-.in(query(:age, :integer, optional: true))
-.in(query(:active, :boolean))
+GET('/search')
+  .query(:q, T.string(min_length: 1), description: 'Search query')
+  .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)), description: 'Results limit')
+  .query(:sort, T.optional(T.string(enum: %w[name date relevance])), description: 'Sort order')
+  .query(:tags, T.optional(T.array(T.string)), description: 'Filter tags')
 ```
 
 ### Path Parameters
+
 ```ruby
-.in(path_param(:id, :integer))
-.in(path_param(:slug, :string))
+GET('/users/:id')
+  .path_param(:id, T.integer(minimum: 1), description: 'User ID')
+
+GET('/files/:category/:filename')
+  .path_param(:category, T.string(enum: %w[images documents videos]), description: 'File category')
+  .path_param(:filename, T.string(pattern: /^[\w\-_.]+$/), description: 'Filename')
 ```
 
-### Headers
+### Request Headers
+
 ```ruby
-.in(header(:authorization, :string))
-.in(header(:'content-type', :string))
+POST('/upload')
+  .header('Content-Type', T.string, description: 'MIME type of uploaded content')
+  .header('X-Request-ID', T.optional(T.string), description: 'Request tracking ID')
+  .header('Authorization', T.string, description: 'Bearer token')
 ```
 
 ### Request Body
+
+```ruby
+# JSON body with schema
+POST('/users')
+  .body(T.hash({
+    "name" => T.string(min_length: 1, max_length: 100),
+    "email" => T.email,
+    "age" => T.optional(T.integer(minimum: 18, maximum: 120)),
+    "preferences" => T.optional(T.hash({
+      "theme" => T.string(enum: %w[light dark]),
+      "notifications" => T.boolean
+    }))
+  }), description: 'User data to create')
+
+# File upload
+POST('/files')
+  .body(T.string, content_type: 'multipart/form-data', description: 'File content')
+
+# Raw binary data
+POST('/images')
+  .body(T.string, content_type: 'image/jpeg', description: 'JPEG image data')
+```
+
+## Output Definitions
+
+### Success Responses
+
+```ruby
+GET('/users')
+  .ok(T.array(USER_SCHEMA), description: 'List of users')
+
+POST('/users')
+  .created(USER_SCHEMA, description: 'Created user')
+
+PUT('/users/:id')  
+  .ok(USER_SCHEMA, description: 'Updated user')
+
+DELETE('/users/:id')
+  .no_content(description: 'User deleted successfully')
+```
+
+### Error Responses
+
 ```ruby
-.in(body({ name: :string, email: :string }))
-.in(body(User)) # Custom class
+GET('/users/:id')
+  .ok(USER_SCHEMA)
+  .error_response(404, T.hash({
+    "error" => T.string,
+    "user_id" => T.integer
+  }), description: 'User not found')
+  .error_response(500, T.hash({
+    "error" => T.string,
+    "trace_id" => T.string
+  }), description: 'Internal server error')
+
+POST('/users')
+  .created(USER_SCHEMA)
+  .error_response(400, T.hash({
+    "error" => T.string,
+    "validation_errors" => T.array(T.hash({
+      "field" => T.string,
+      "message" => T.string,
+      "code" => T.string
+    }))
+  }), description: 'Validation failed')
+  .error_response(409, T.hash({
+    "error" => T.string,
+    "existing_user_id" => T.integer
+  }), description: 'User already exists')
 ```
 
-## Output DSL Helpers
+### Multiple Response Types
 
-### JSON Response
 ```ruby
-.out(json_body({ id: :integer, name: :string }))
-.out(json_body([{ id: :integer, name: :string }])) # Array
+GET('/content/:id')
+  .path_param(:id, T.integer)
+  .query(:format, T.optional(T.string(enum: %w[json xml])), description: 'Response format')
+  .ok(CONTENT_SCHEMA, content_type: 'application/json', description: 'JSON response')
+  .ok(T.string, content_type: 'application/xml', description: 'XML response')
+  .error_response(404, ERROR_SCHEMA)
 ```
 
-### XML Response
+## Metadata and Documentation
+
+### Basic Metadata
+
 ```ruby
-.out(xml_body({ message: :string }))
+GET('/users')
+  .summary('List all users')
+  .description('Retrieves a paginated list of all users in the system with optional filtering')
+  .tags('Users', 'CRUD')
+  .deprecated(false)
 ```
 
-### Status Codes
+### Rich Documentation
+
 ```ruby
-.out(status_code(200))
-.out(status_code(201))
-.out(status_code(204))
+POST('/users')
+  .summary('Create a new user')
+  .description('''
+    Creates a new user account with the provided information.
+    
+    The email address must be unique across the system.
+    Password requirements:
+    - Minimum 8 characters
+    - At least one uppercase letter
+    - At least one number
+    - At least one special character
+  ''')
+  .tags('Users', 'Registration')
+  .external_docs(
+    description: 'User Management Guide',
+    url: 'https://docs.example.com/users'
+  )
 ```
 
-### Error Responses
+### OpenAPI Extensions
+
 ```ruby
-.error_out(404, json_body({ error: :string }))
-.error_out(422, json_body({ error: :string, details: :string }))
+GET('/users')
+  .openapi_extensions({
+    'x-rate-limit' => '100/minute',
+    'x-permissions' => ['users:read'],
+    'x-cache-ttl' => 300
+  })
 ```
 
-## Metadata Helpers
+## Advanced Features
+
+### Authentication Requirements
+
+```ruby
+GET('/profile')
+  .bearer_auth(scopes: ['profile:read'])
+  .ok(USER_SCHEMA)
+
+DELETE('/admin/users/:id')
+  .bearer_auth(scopes: ['admin', 'users:delete'])
+  .no_content()
+```
+
+### AI Integration
 
-### Documentation
 ```ruby
-.description('Retrieve user by ID')
-.summary('Get user')
-.tag('users')
+GET('/search/semantic')
+  .query(:query, T.string, description: 'Natural language search query')
+  .enable_rag(
+    retrieval_backend: :memory,
+    llm_provider: :openai,
+    context_window: 4000
+  )
+  .enable_mcp # Export for AI agents
+  .enable_llm_instructions(purpose: :completion)
+  .ok(T.hash({
+    "results" => T.array(SEARCH_RESULT_SCHEMA),
+    "reasoning" => T.string,
+    "confidence" => T.float
+  }))
 ```
 
-### Lifecycle
+### Observability
+
 ```ruby
-.deprecated(true)     # Mark as deprecated
-.deprecated(false)    # Not deprecated
+GET('/users/:id')
+  .path_param(:id, T.integer)
+  .with_metrics('user_requests', labels: { operation: 'get_by_id' })
+  .with_tracing('fetch_user')
+  .ok(USER_SCHEMA)
 ```
 
-### Examples
+### Caching
+
 ```ruby
-.example({ name: 'John', email: 'john@example.com' })
+GET('/users/:id')
+  .cache(ttl: 300, vary: ['Authorization'])
+  .ok(USER_SCHEMA)
 ```
 
-## Supported Types
+## Type System Integration
 
-- `:string` - String values
-- `:integer` - Integer values
-- `:float` - Float values (accepts integers too)
-- `:boolean` - Boolean values (true/false)
-- `:date` - Date objects or ISO date strings
-- `:datetime` - DateTime objects or ISO datetime strings
-- `Hash` - Hash schemas with typed keys
-- `Class` - Custom class types
+### Using the T Shortcut
 
-## Complete Example
+The global `T` constant provides clean access to all RapiTapir types:
 
 ```ruby
-require 'rapitapir'
+# Primitive types
+T.string                    # String type
+T.integer                   # Integer type
+T.float                     # Float type
+T.boolean                   # Boolean type
+T.date                      # Date type
+T.datetime                  # DateTime type
+
+# Constrained types
+T.string(min_length: 1, max_length: 100)
+T.integer(minimum: 0, maximum: 999)
+T.float(minimum: 0.0)
+
+# Special types
+T.email                     # Email validation
+T.uuid                      # UUID format
+T.url                       # URL format
+
+# Collections
+T.array(T.string)           # Array of strings
+T.hash({ "key" => T.value }) # Object schema
+
+# Optional types
+T.optional(T.string)        # Nullable string
+```
 
-# Define a complete CRUD endpoint
-user_endpoint = RapiTapir.post('/users')
-  .in(header(:authorization, :string))
-  .in(header(:'content-type', :string))
-  .in(body({ 
-    name: :string, 
-    email: :string, 
-    age: :integer,
-    active: :boolean
-  }))
-  .out(status_code(201))
-  .out(json_body({ 
-    id: :integer, 
-    name: :string, 
-    email: :string,
-    created_at: :datetime
-  }))
-  .error_out(400, json_body({ error: :string, details: :string }))
-  .error_out(422, json_body({ 
-    error: :string, 
-    validation_errors: [{ field: :string, message: :string }] 
-  }))
-  .description('Create a new user account')
-  .summary('Create user')
-  .tag('users')
-  .example({ name: 'John Doe', email: 'john@example.com', age: 30, active: true })
-
-# Validate inputs and outputs
-input_data = { 
-  body: { name: 'John', email: 'john@example.com', age: 30, active: true }
-}
-output_data = {
+### Auto-Derivation
+
+Generate schemas from existing data:
+
+```ruby
+# From hash
+USER_SCHEMA = T.from_hash({
   id: 1,
-  name: 'John',
-  email: 'john@example.com',
-  created_at: DateTime.now
-}
+  name: "John Doe",
+  active: true,
+  tags: ["admin"]
+})
 
-user_endpoint.validate!(input_data, output_data) # Returns true or raises TypeError
+# From JSON Schema
+API_SCHEMA = T.from_json_schema(json_schema_object)
 
-# Get endpoint metadata
-puts user_endpoint.metadata[:description] # "Create a new user account"
-puts user_endpoint.to_h # Complete hash representation
+# From OpenStruct
+CONFIG_SCHEMA = T.from_open_struct(config_object)
 ```
 
-## Type Validation
+### Schema Composition
 
-RapiTapir performs runtime type validation:
+```ruby
+# Base schemas
+ADDRESS_SCHEMA = T.hash({
+  "street" => T.string,
+  "city" => T.string,
+  "country" => T.string,
+  "postal_code" => T.string
+})
+
+# Composed schemas
+USER_SCHEMA = T.hash({
+  "id" => T.integer,
+  "name" => T.string,
+  "email" => T.email,
+  "address" => T.optional(ADDRESS_SCHEMA),
+  "billing_address" => T.optional(ADDRESS_SCHEMA)
+})
+```
+
+## Complete Examples
+
+### Simple CRUD Endpoint
 
 ```ruby
-endpoint = RapiTapir.get('/users/:id')
-  .in(path_param(:id, :integer))
-  .out(json_body({ name: :string }))
+class UserAPI < SinatraRapiTapir
+  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
+  })
+
+  # List users
+  endpoint(
+    GET('/users')
+      .summary('List users')
+      .query(:active, T.optional(T.boolean), description: 'Filter by active status')
+      .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)), description: 'Page size')
+      .query(:offset, T.optional(T.integer(minimum: 0)), description: 'Page offset')
+      .tags('Users')
+      .ok(T.hash({
+        "users" => T.array(USER_SCHEMA),
+        "total" => T.integer,
+        "limit" => T.integer,
+        "offset" => T.integer
+      }))
+      .build
+  ) do |inputs|
+    users = User.all
+    users = users.where(active: inputs[:active]) if inputs[:active]
+    
+    limit = inputs[:limit] || 50
+    offset = inputs[:offset] || 0
+    
+    paginated_users = users.limit(limit).offset(offset)
+    
+    {
+      users: paginated_users.map(&:to_h),
+      total: users.count,
+      limit: limit,
+      offset: offset
+    }
+  end
+
+  # Get user by ID
+  endpoint(
+    GET('/users/:id')
+      .summary('Get user by ID')
+      .path_param(:id, T.integer(minimum: 1), description: 'User ID')
+      .tags('Users')
+      .ok(USER_SCHEMA, description: 'User details')
+      .error_response(404, T.hash({
+        "error" => T.string,
+        "user_id" => T.integer
+      }), description: 'User not found')
+      .build
+  ) do |inputs|
+    user = User.find(inputs[:id])
+    halt 404, { error: 'User not found', user_id: inputs[:id] }.to_json unless user
+    user.to_h
+  end
+
+  # Create user
+  endpoint(
+    POST('/users')
+      .summary('Create a new user')
+      .body(T.hash({
+        "name" => T.string(min_length: 1, max_length: 100),
+        "email" => T.email,
+        "active" => T.optional(T.boolean)
+      }), description: 'User data')
+      .tags('Users')
+      .created(USER_SCHEMA, description: 'Created user')
+      .error_response(400, T.hash({
+        "error" => T.string,
+        "validation_errors" => T.array(T.string)
+      }), description: 'Validation failed')
+      .error_response(409, T.hash({
+        "error" => T.string,
+        "existing_email" => T.string
+      }), description: 'Email already exists')
+      .build
+  ) do |inputs|
+    begin
+      user = User.create!(inputs[:body])
+      status 201
+      user.to_h
+    rescue ValidationError => e
+      halt 400, {
+        error: 'Validation failed',
+        validation_errors: e.messages
+      }.to_json
+    rescue UniqueConstraintError => e
+      halt 409, {
+        error: 'Email already exists',
+        existing_email: inputs[:body]['email']
+      }.to_json
+    end
+  end
+end
+```
 
-# This will pass
-endpoint.validate!({ id: 123 }, { name: 'John' })
+### Advanced API with Authentication and AI
 
-# This will raise TypeError
-endpoint.validate!({ id: 'abc' }, { name: 'John' })
-endpoint.validate!({ id: 123 }, { name: 123 })
+```ruby
+class AdvancedAPI < SinatraRapiTapir
+  rapitapir do
+    info(title: 'Advanced API', version: '2.0.0')
+    
+    oauth2_auth0 :auth0,
+      domain: ENV['AUTH0_DOMAIN'],
+      audience: ENV['AUTH0_AUDIENCE']
+    
+    production_defaults!
+  end
+
+  # AI-powered search endpoint
+  endpoint(
+    GET('/search/intelligent')
+      .summary('AI-powered intelligent search')
+      .description('Uses machine learning to understand natural language queries and return relevant results')
+      .query(:q, T.string(min_length: 1), description: 'Natural language search query')
+      .query(:limit, T.optional(T.integer(minimum: 1, maximum: 50)), description: 'Maximum results')
+      .query(:include_reasoning, T.optional(T.boolean), description: 'Include AI reasoning in response')
+      .bearer_auth(scopes: ['search:enhanced'])
+      .tags('Search', 'AI')
+      .ok(T.hash({
+        "results" => T.array(T.hash({
+          "id" => T.string,
+          "title" => T.string,
+          "content" => T.string,
+          "relevance_score" => T.float(minimum: 0, maximum: 1),
+          "metadata" => T.hash({})
+        })),
+        "query_analysis" => T.hash({
+          "intent" => T.string,
+          "entities" => T.array(T.string),
+          "confidence" => T.float(minimum: 0, maximum: 1)
+        }),
+        "reasoning" => T.optional(T.string),
+        "total_results" => T.integer,
+        "processing_time_ms" => T.float
+      }))
+      .error_response(400, T.hash({
+        "error" => T.string,
+        "suggestion" => T.string
+      }), description: 'Invalid query')
+      .error_response(401, T.hash({ "error" => T.string }), description: 'Authentication required')
+      .error_response(403, T.hash({ "error" => T.string }), description: 'Insufficient permissions')
+      .enable_rag(
+        retrieval_backend: :elasticsearch,
+        llm_provider: :openai,
+        context_window: 8000
+      )
+      .enable_llm_instructions(purpose: :analysis)
+      .with_metrics('ai_search_requests', labels: { model: 'gpt-4' })
+      .with_tracing('intelligent_search')
+      .build
+  ) do |inputs|
+    start_time = Time.now
+    
+    begin
+      # Verify enhanced search permissions
+      require_scope!('search:enhanced')
+      
+      # Perform AI-enhanced search
+      search_results = AISearchService.intelligent_search(
+        query: inputs[:q],
+        limit: inputs[:limit] || 20,
+        user_context: current_auth_context[:user_info],
+        rag_context: rag_context
+      )
+      
+      response = {
+        results: search_results[:items],
+        query_analysis: search_results[:analysis],
+        total_results: search_results[:total],
+        processing_time_ms: ((Time.now - start_time) * 1000).round(2)
+      }
+      
+      # Include reasoning if requested
+      if inputs[:include_reasoning]
+        response[:reasoning] = search_results[:reasoning]
+      end
+      
+      response
+      
+    rescue InvalidQueryError => e
+      halt 400, {
+        error: e.message,
+        suggestion: e.suggestion
+      }.to_json
+    end
+  end
+end
 ```
 
-## Immutability
+## Best Practices
+
+### 1. Schema Organization
+```ruby
+# Define schemas as constants for reuse
+USER_SCHEMA = T.hash({
+  "id" => T.integer,
+  "name" => T.string,
+  "email" => T.email
+})
+
+# Use schema composition
+FULL_USER_SCHEMA = T.hash({
+  **USER_SCHEMA.definition,
+  "profile" => T.optional(PROFILE_SCHEMA),
+  "preferences" => T.optional(PREFERENCES_SCHEMA)
+})
+```
 
-All endpoint operations return new endpoint instances, preserving immutability:
+### 2. Error Handling
+```ruby
+# Define consistent error schemas
+ERROR_SCHEMA = T.hash({
+  "error" => T.string,
+  "code" => T.string,
+  "details" => T.optional(T.hash({}))
+})
+
+# Use specific error responses
+.error_response(400, VALIDATION_ERROR_SCHEMA, description: 'Validation failed')
+.error_response(404, NOT_FOUND_ERROR_SCHEMA, description: 'Resource not found')
+.error_response(500, INTERNAL_ERROR_SCHEMA, description: 'Internal server error')
+```
 
+### 3. Documentation
 ```ruby
-base = RapiTapir.get('/users')
-with_auth = base.in(header(:authorization, :string))
-with_output = with_auth.out(json_body({ users: [:string] }))
+# Always provide clear summaries and descriptions
+.summary('Create user account')
+.description('Creates a new user account with email verification')
+
+# Use meaningful parameter descriptions
+.query(:filter, T.optional(T.string), description: 'Filter users by name or email')
 
-# base, with_auth, and with_output are all different objects
-puts base.inputs.length      # 0
-puts with_auth.inputs.length # 1
-puts with_output.inputs.length # 1
-puts with_output.outputs.length # 1
+# Tag endpoints for logical grouping
+.tags('Users', 'Account Management')
 ```
 
-## Error Handling
+### 4. Type Safety
+```ruby
+# Use specific constraints
+T.string(min_length: 1, max_length: 255)
+T.integer(minimum: 1)
+T.array(T.string, min_items: 1)
+
+# Prefer enums for known values
+T.string(enum: %w[active inactive pending])
 
-The DSL provides comprehensive error handling with detailed messages:
+# Use optional for nullable fields
+T.optional(T.string)
+```
 
+### 5. Performance
 ```ruby
-# ArgumentError for invalid parameters
-query(nil, :string)          # "Input name cannot be nil"
-status_code(999)             # "Invalid status code: 999"
+# Add caching for expensive operations
+.cache(ttl: 300, vary: ['Authorization'])
+
+# Use metrics for monitoring
+.with_metrics('endpoint_requests', labels: { operation: 'list' })
 
-# TypeError for validation failures
-endpoint.validate!({ name: 123 }, {}) # "Invalid type for input 'name': expected string, got Integer"
+# Add tracing for debugging
+.with_tracing('database_query')
 ```
 
 ---
 
-For more examples and advanced usage, see the files in the `examples/` directory and the implementation plan in `docs/blueprint.md`.
+This guide covers the comprehensive RapiTapir endpoint definition DSL. For more examples, see the [examples directory](../examples/) and the [Sinatra extension guide](SINATRA_EXTENSION.md).