rapitapir 0.1.0

data/docs/phase3-plan.md

@@ -0,0 +1,108 @@
+# Phase 3: Client Generation & Documentation Implementation Plan
+
+## Overview
+Phase 3 focuses on generating OpenAPI specifications, client SDKs, and documentation from RapiTapir endpoint definitions.
+
+## Core Components
+
+### 1. OpenAPI Schema Generation (`lib/rapitapir/openapi/`) ✅ COMPLETE
+- ✅ `schema_generator.rb` - Main OpenAPI 3.0 schema generation
+- ✅ Type mapping - Maps RapiTapir types to OpenAPI schemas
+- ✅ Path generation - Generates OpenAPI paths from endpoints  
+- ✅ Component generation - Generates reusable components/schemas
+
+### 2. Client Generation (`lib/rapitapir/client/`) ✅ TypeScript COMPLETE
+- ✅ `generator_base.rb` - Base class for client generators
+- ✅ `typescript_generator.rb` - TypeScript/JavaScript client
+- [ ] `python_generator.rb` - Python client
+- [ ] `curl_generator.rb` - cURL examples
+- [ ] `template_engine.rb` - Template rendering system
+
+### 3. Documentation (`lib/rapitapir/docs/`)
+- [ ] `markdown_generator.rb` - API documentation in Markdown
+- [ ] `html_generator.rb` - HTML documentation with styling
+- [ ] `postman_generator.rb` - Postman collection export
+
+### 4. CLI Tools (`lib/rapitapir/cli/`)
+- [ ] `command.rb` - Main CLI interface
+- [ ] `generate.rb` - Generation commands
+- [ ] `serve.rb` - Documentation server
+
+## Features
+
+### OpenAPI Schema Features ✅ COMPLETE
+- ✅ Basic endpoint definition
+- ✅ Complete OpenAPI 3.0 schema generation
+- ✅ Request/response schema mapping
+- ✅ Path parameter conversion (:id → {id})
+- ✅ HTTP method support (GET, POST, PUT, DELETE, PATCH, etc.)
+- ✅ JSON/YAML output formats
+- ✅ Metadata integration (summary, description, tags)
+- [ ] Authentication schemes
+- [ ] Tags and operation grouping
+- [ ] Examples and descriptions
+
+### Client Generation Features ✅ TypeScript COMPLETE
+- ✅ TypeScript client with type safety
+- ✅ HTTP client abstraction with fetch API
+- ✅ Error handling with custom error types
+- ✅ Request/response type generation
+- ✅ Path parameter interpolation
+- ✅ Query parameter handling
+- ✅ Optional parameter support
+- ✅ Configurable client (base URL, headers, timeout)
+- [ ] Python client with type hints
+- [ ] Authentication integration
+
+### Documentation Features
+- [ ] Interactive API documentation
+- [ ] Code examples
+- [ ] Try-it-out functionality
+- [ ] Markdown export
+- [ ] Postman collection export
+
+## Implementation Status
+
+### Phase 3.1: OpenAPI Generation ✅ COMPLETE
+- Full OpenAPI 3.0.3 schema generation
+- Type mapping from Ruby to OpenAPI types
+- Path parameter conversion
+- Request/response documentation
+- JSON and YAML output formats
+- 11 comprehensive tests
+- Working examples
+
+### Phase 3.2: TypeScript Client Generator ✅ COMPLETE
+- Complete TypeScript client generation
+- Type-safe interfaces for all endpoints
+- Fetch-based HTTP client implementation
+- Smart method naming (getUsers, createUser, getUserById)
+- Optional parameter handling
+- Error handling with ApiError types
+- Configurable client settings
+- 36 comprehensive tests (19 TypeScript + 17 Base)
+- Working examples and usage documentation
+
+### Current Progress: 88.33% test coverage, 159 tests passing
+
+## Implementation Order
+1. ✅ OpenAPI schema generator (core functionality)
+2. ✅ TypeScript client generator  
+3. [ ] Documentation generator
+4. [ ] CLI tools
+5. [ ] Additional client generators (Python, etc.)
+
+## Testing Strategy ✅ IMPLEMENTED
+- ✅ Unit tests for each generator
+- ✅ Integration tests with real API definitions
+- ✅ Generated client validation
+- ✅ OpenAPI schema validation
+- ✅ Type conversion testing
+- ✅ Method name generation testing
+- ✅ Parameter extraction testing
+
+## Next Steps
+1. **Documentation Generator**: HTML and Markdown documentation generation
+2. **CLI Tools**: Command-line interface for all generators
+3. **Python Client Generator**: Type-hinted Python client with requests
+4. **Additional Features**: Authentication, advanced error handling, more examples

data/docs/sinatra_rapitapir.md

@@ -0,0 +1,87 @@
+# SinatraRapiTapir - Clean Base Class
+
+## Overview
+
+`SinatraRapiTapir` is a new base class that provides the cleanest possible syntax for creating RapiTapir APIs with Sinatra. It automatically includes all RapiTapir functionality without any manual setup.
+
+## Before vs After
+
+### Before (Manual Extension Registration)
+```ruby
+require 'sinatra/base'
+require_relative '../lib/rapitapir/sinatra/extension'
+
+class MyAPI < Sinatra::Base
+  register RapiTapir::Sinatra::Extension
+  
+  rapitapir do
+    info(title: 'My API', version: '1.0.0')
+    development_defaults!
+  end
+
+  endpoint(
+    GET('/hello').ok(string_response).build
+  ) { { message: 'Hello!' } }
+end
+```
+
+### After (Clean Base Class)
+```ruby
+require_relative '../lib/rapitapir'
+
+class MyAPI < SinatraRapiTapir
+  rapitapir do
+    info(title: 'My API', version: '1.0.0')
+    development_defaults!
+  end
+
+  endpoint(
+    GET('/hello').ok(string_response).build
+  ) { { message: 'Hello!' } }
+end
+```
+
+## Key Benefits
+
+1. **Cleaner Syntax**: `class MyAPI < SinatraRapiTapir` vs manual extension registration
+2. **Fewer Requires**: Only need to require `rapitapir`, not individual extensions
+3. **Automatic Setup**: Extension is automatically registered
+4. **Enhanced DSL**: HTTP verb methods (GET, POST, etc.) are automatically available
+5. **Full Compatibility**: Works identically to manual extension registration
+6. **Type Safety**: Maintains all FluentEndpointBuilder functionality
+
+## Features Automatically Included
+
+- ✅ Enhanced HTTP verb DSL (`GET()`, `POST()`, `PUT()`, etc.)
+- ✅ RapiTapir extension with all features
+- ✅ Automatic health check endpoints
+- ✅ OpenAPI documentation generation
+- ✅ CORS and security middleware
+- ✅ Type validation and error handling
+- ✅ Authentication and authorization helpers
+
+## Usage
+
+The `SinatraRapiTapir` class is available in two ways:
+
+1. **Namespaced**: `RapiTapir::SinatraRapiTapir`
+2. **Top-level**: `SinatraRapiTapir` (for convenience)
+
+Both are equivalent and can be used interchangeably.
+
+## Examples
+
+- `examples/hello_world.rb` - Minimal API demonstration
+- `examples/getting_started_extension.rb` - Full bookstore API
+
+## Backward Compatibility
+
+The new base class is 100% backward compatible. Existing code using manual extension registration continues to work unchanged.
+
+## Testing
+
+Comprehensive test coverage is provided in `spec/sinatra/sinatra_rapitapir_spec.rb` with:
+- Inheritance verification
+- Enhanced DSL testing
+- Feature compatibility testing
+- Backward compatibility validation

data/docs/type_shortcuts.md

@@ -0,0 +1,146 @@
+# Type Shortcuts in RapiTapir
+
+## Overview
+
+RapiTapir provides a global `T` constant as a shortcut for `RapiTapir::Types`, making your type definitions much cleaner and more readable. **No manual setup required** - the `T` shortcut is automatically available when you `require 'rapitapir'`.
+
+## Before vs After
+
+### Before (Verbose)
+```ruby
+USER_SCHEMA = RapiTapir::Types.hash({
+  "id" => RapiTapir::Types.integer,
+  "name" => RapiTapir::Types.string(min_length: 1, max_length: 100),
+  "email" => RapiTapir::Types.email,
+  "age" => RapiTapir::Types.optional(RapiTapir::Types.integer(min: 0, max: 150))
+})
+```
+
+### After (Clean)
+```ruby
+USER_SCHEMA = T.hash({
+  "id" => T.integer,
+  "name" => T.string(min_length: 1, max_length: 100),
+  "email" => T.email,
+  "age" => T.optional(T.integer(min: 0, max: 150))
+})
+```
+
+## Automatic Availability
+
+The `T` shortcut is **globally available** after requiring RapiTapir:
+
+```ruby
+require 'rapitapir'
+
+# T is immediately available everywhere - no setup needed!
+BOOK_SCHEMA = T.hash({
+  "title" => T.string,
+  "pages" => T.integer
+})
+
+class MyAPI < SinatraRapiTapir
+  # T works inside classes too
+  USER_SCHEMA = T.hash({
+    "name" => T.string,
+    "email" => T.email
+  })
+  
+  endpoint(
+    GET('/books')
+      .ok(T.array(BOOK_SCHEMA)) # And in endpoint definitions
+      .build
+  ) { Book.all }
+end
+```
+
+## All Available Type Shortcuts
+
+```ruby
+# Primitive types
+T.string(min_length: 1, max_length: 255)
+T.integer(minimum: 0, maximum: 100)
+T.float(minimum: 0.0)
+T.boolean
+T.date
+T.datetime
+T.uuid
+T.email
+
+# Composite types
+T.array(T.string)
+T.hash({ "key" => T.string })
+T.optional(T.string)
+
+# Complex object types
+T.object do
+  field :id, T.integer
+  field :name, T.string
+end
+```
+
+## Usage in Endpoints
+
+```ruby
+class MyAPI < SinatraRapiTapir
+  endpoint(
+    GET('/users/:id')
+      .path_param(:id, T.integer(minimum: 1))
+      .query(:include, T.optional(T.array(T.string)))
+      .ok(T.hash({
+        "user" => USER_SCHEMA,
+        "metadata" => T.hash({
+          "version" => T.string,
+          "timestamp" => T.datetime
+        })
+      }))
+      .error_out(404, T.hash({ "error" => T.string }))
+      .build
+  ) do |inputs|
+    # Your endpoint logic
+  end
+end
+```
+
+## Benefits
+
+1. **Automatic Setup**: Available immediately after `require 'rapitapir'` - no manual configuration
+2. **Readability**: Much cleaner type definitions  
+3. **Less Typing**: Shorter syntax reduces boilerplate
+4. **Consistency**: Same T prefix for all types
+5. **Familiar**: Similar to TypeScript's type syntax
+6. **Global Scope**: Works everywhere - classes, modules, top-level code
+7. **Backward Compatible**: `RapiTapir::Types` still works
+
+## Alternative Approaches
+
+If you prefer your own shortcut, you can create it:
+
+```ruby
+# Custom shortcut (but T is already provided!)
+Types = RapiTapir::Types
+
+# Or even shorter
+RT = RapiTapir::Types
+
+# Use it
+USER_SCHEMA = Types.hash({ "name" => Types.string })
+```
+
+**Note**: The global `T` constant is automatically available when you `require 'rapitapir'` - no need to define your own unless you prefer a different name.
+
+## Implementation
+
+The T shortcut is implemented in the main RapiTapir library file:
+
+```ruby
+# In lib/rapitapir.rb
+module RapiTapir
+  # ... RapiTapir module code ...
+end
+
+# Global shortcut constant
+T = RapiTapir::Types
+```
+
+This means that as soon as you require RapiTapir, the `T` constant becomes available throughout your entire application.

data/examples/README_ENTERPRISE.md

@@ -0,0 +1,202 @@
+# Enterprise RapiTapir API - Auto-Generated OpenAPI Implementation
+
+This is the improved version of the Enterprise Sinatra API that demonstrates RapiTapir's capability to automatically generate OpenAPI 3.0 specifications from endpoint definitions at runtime.
+
+## 🎯 Key Improvements
+
+### ✅ **Fixed Issues from Original Version**
+
+1. **Auto-Generated OpenAPI**: The OpenAPI specification is now generated automatically from RapiTapir endpoint definitions at runtime, not manually written
+2. **Working Run Script**: Fixed the `run_enterprise_api.rb` script to properly load dependencies with `bundle exec`
+3. **Proper RapiTapir DSL Usage**: All endpoints are now defined using RapiTapir's fluent DSL with proper type definitions
+4. **Runtime Reflection**: The API documentation reflects the actual endpoint implementations
+
+### 🚀 **Enterprise Features**
+
+- **8 Fully-Typed Endpoints** defined with RapiTapir DSL
+- **Auto-Generated OpenAPI 3.0** specification from endpoint definitions
+- **Bearer Token Authentication** with scope-based authorization
+- **Production Middleware Stack**: CORS, Rate Limiting, Security Headers
+- **Interactive Documentation** with Swagger UI
+- **Type-Safe Request/Response** schemas using RapiTapir Types
+
+## 📋 API Endpoints (Auto-Generated from RapiTapir Definitions)
+
+All endpoints are defined using RapiTapir's fluent DSL and automatically generate OpenAPI documentation:
+
+### System Endpoints
+- **GET /health** - Health check (public)
+- **GET /docs** - Interactive Swagger UI documentation  
+- **GET /openapi.json** - Auto-generated OpenAPI 3.0 specification
+
+### Task Management Endpoints (Authenticated)
+- **GET /api/v1/tasks** - List all tasks (requires `read` scope)
+- **GET /api/v1/tasks/:id** - Get specific task (requires `read` scope)
+- **POST /api/v1/tasks** - Create new task (requires `write` scope)
+- **PUT /api/v1/tasks/:id** - Update task (requires `write` scope)
+- **DELETE /api/v1/tasks/:id** - Delete task (requires `admin` scope)
+
+### User Endpoints (Authenticated)
+- **GET /api/v1/profile** - Get current user profile with assigned tasks
+- **GET /api/v1/admin/users** - List all users (requires `admin` scope)
+
+## 🔑 Authentication
+
+Three test Bearer tokens are provided:
+
+```bash
+# Regular user (read, write permissions)
+Authorization: Bearer user-token-123
+
+# Admin user (read, write, admin, delete permissions) 
+Authorization: Bearer admin-token-456
+
+# Read-only user (read permission only)
+Authorization: Bearer readonly-token-789
+```
+
+## 🏃‍♂️ **Running the API**
+
+### Start the Server
+```bash
+cd /Users/riccardo/git/github/riccardomerolla/rapitapir
+bundle exec ruby examples/run_enterprise_api.rb
+```
+
+### Access Documentation
+- **Interactive Docs**: http://localhost:4567/docs
+- **OpenAPI Spec**: http://localhost:4567/openapi.json  
+- **Health Check**: http://localhost:4567/health
+
+## 📖 **Example API Calls**
+
+### Health Check (Public)
+```bash
+curl http://localhost:4567/health
+```
+
+### List Tasks (Authenticated)
+```bash
+curl -H "Authorization: Bearer user-token-123" \
+     http://localhost:4567/api/v1/tasks
+```
+
+### Create Task (Authenticated)
+```bash
+curl -X POST \
+     -H "Authorization: Bearer user-token-123" \
+     -H "Content-Type: application/json" \
+     -d '{"title":"New Task","description":"Test task","assignee_id":1}' \
+     http://localhost:4567/api/v1/tasks
+```
+
+### Get User Profile (Authenticated)
+```bash
+curl -H "Authorization: Bearer user-token-123" \
+     http://localhost:4567/api/v1/profile
+```
+
+### Admin: List All Users (Admin Only)
+```bash
+curl -H "Authorization: Bearer admin-token-456" \
+     http://localhost:4567/api/v1/admin/users
+```
+
+## 🎯 **RapiTapir DSL Example**
+
+The endpoints are defined using RapiTapir's fluent DSL with full type safety:
+
+```ruby
+# Task creation endpoint with full type validation
+RapiTapir.post('/api/v1/tasks')
+  .summary('Create a new task')
+  .description('Create a new task in the system. Requires write permission.')
+  .json_body(TASK_CREATE_SCHEMA)  # RapiTapir type schema
+  .created(TASK_SCHEMA)           # Response type validation
+  .error_response(400, ERROR_SCHEMA, description: 'Validation error')
+  .error_response(401, ERROR_SCHEMA, description: 'Authentication required')
+  .error_response(403, ERROR_SCHEMA, description: 'Insufficient permissions')
+  .build
+```
+
+## 🔧 **Auto-Generated OpenAPI Features**
+
+The OpenAPI specification is generated automatically from the RapiTapir endpoint definitions:
+
+- **Path Parameters**: Automatically extracted from `:id` patterns
+- **Query Parameters**: Type-safe with validation rules
+- **Request Bodies**: JSON schema validation from RapiTapir types
+- **Response Schemas**: Type-safe response definitions
+- **Error Responses**: Comprehensive error documentation
+- **Security Schemes**: Bearer token authentication documented
+- **Operation Metadata**: Summaries, descriptions, and tags
+
+## 🏗️ **Architecture Highlights**
+
+### Type-Safe Schema Definitions
+```ruby
+TASK_SCHEMA = RapiTapir::Types.hash({
+  "id" => RapiTapir::Types.integer,
+  "title" => RapiTapir::Types.string,
+  "description" => RapiTapir::Types.string,
+  "status" => RapiTapir::Types.string,
+  "assignee_id" => RapiTapir::Types.integer,
+  "created_at" => RapiTapir::Types.string,
+  "updated_at" => RapiTapir::Types.optional(RapiTapir::Types.string)
+})
+```
+
+### Auto-Generated OpenAPI
+```ruby
+def self.openapi_spec
+  @openapi_spec ||= begin
+    generator = RapiTapir::OpenAPI::SchemaGenerator.new(
+      endpoints: endpoints,
+      info: { title: 'Enterprise Task Management API', version: '1.0.0' }
+    )
+    generator.generate
+  end
+end
+```
+
+### Sinatra Integration
+```ruby
+# OpenAPI endpoint auto-generated at runtime
+get '/openapi.json' do
+  content_type :json
+  JSON.pretty_generate(TaskAPI.openapi_spec)
+end
+```
+
+## ✨ **Production Features**
+
+- **Security Headers**: XSS protection, content type options
+- **CORS Support**: Configurable origins and methods
+- **Rate Limiting**: 100 requests/minute, 2000/hour
+- **Request Validation**: Type-safe input validation
+- **Error Handling**: Structured error responses
+- **Authentication Middleware**: Bearer token validation
+- **Authorization**: Scope-based permission checking
+
+## 🧪 **Testing**
+
+Run the comprehensive test suite:
+
+```bash
+# Test RapiTapir endpoint definitions
+ruby examples/test_rapitapir_endpoints.rb
+
+# Test the full enterprise API (requires server to be running)
+ruby examples/test_enterprise_api.rb
+```
+
+## 🎉 **Benefits of This Approach**
+
+1. **Single Source of Truth**: API endpoints defined once in RapiTapir DSL
+2. **Auto-Generated Documentation**: OpenAPI spec reflects actual implementation
+3. **Type Safety**: Request/response validation with RapiTapir types  
+4. **Developer Experience**: Interactive Swagger UI for testing
+5. **Production Ready**: Comprehensive middleware and security
+6. **Maintainable**: No manual OpenAPI spec maintenance required
+
+This implementation demonstrates the power of RapiTapir's DSL and auto-generation capabilities in creating production-ready APIs with comprehensive documentation.