rapitapir 0.1.0

data/examples/getting_started_extension.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+# RapiTapir Sinatra Extension - Getting Started Example
+#
+# This minimal example shows how easy it is to create an enterprise-grade
+# API with the RapiTapir Sinatra Extension - zero boilerplate!
+
+# Check for Sinatra availability
+begin
+  require 'sinatra/base'
+  SINATRA_AVAILABLE = true
+rescue LoadError
+  SINATRA_AVAILABLE = false
+  puts '⚠️  Sinatra not available. Install with: gem install sinatra'
+  puts '🔄 Running in demo mode instead...'
+end
+
+require_relative '../lib/rapitapir'
+
+# Only require extension if Sinatra is available
+# Note: Extension and SinatraRapiTapir are auto-loaded when requiring rapitapir
+
+# Simple in-memory data store
+class BookStore
+  @@books = [
+    { id: 1, title: 'The Ruby Programming Language', author: 'Matz', isbn: '978-0596516178', published: true },
+    { id: 2, title: 'Metaprogramming Ruby', author: 'Paolo Perrotta', isbn: '978-1934356470', published: true }
+  ]
+  @@next_id = 3
+
+  def self.all
+    @@books
+  end
+
+  def self.find(id)
+    @@books.find { |book| book[:id] == id.to_i }
+  end
+
+  def self.create(attrs)
+    book = attrs.merge(id: @@next_id)
+    @@next_id += 1
+    @@books << book
+    book
+  end
+
+  def self.update(id, attrs)
+    book = find(id)
+    return nil unless book
+
+    attrs.each { |key, value| book[key] = value }
+    book
+  end
+
+  def self.delete(id)
+    @@books.reject! { |book| book[:id] == id.to_i }
+  end
+end
+
+# Define the book schema
+BOOK_SCHEMA = RapiTapir::Types.hash({
+                                      'id' => RapiTapir::Types.integer,
+                                      'title' => RapiTapir::Types.string,
+                                      'author' => RapiTapir::Types.string,
+                                      'isbn' => RapiTapir::Types.string,
+                                      'published' => RapiTapir::Types.boolean
+                                    })
+
+# Schema for creating books (without ID)
+BOOK_CREATE_SCHEMA = RapiTapir::Types.hash({
+                                             'title' => RapiTapir::Types.string,
+                                             'author' => RapiTapir::Types.string,
+                                             'isbn' => RapiTapir::Types.string,
+                                             'published' => RapiTapir::Types.boolean
+                                           })
+
+# Your API application - incredibly simple!
+if SINATRA_AVAILABLE
+  class BookstoreAPI < SinatraRapiTapir
+
+    # One-line configuration for the entire API
+    rapitapir do
+      info(
+        title: 'Bookstore API',
+        description: 'A simple bookstore API built with SinatraRapiTapir',
+        version: '1.0.0'
+      )
+
+      development_defaults! # Sets up CORS, rate limiting, docs, health check, etc.
+      add_public_paths('/books') # No auth required for books (health check is auto-public)
+    end
+
+    # Full RESTful books resource - individual endpoints for better control
+    
+    # List all books
+    endpoint(
+      GET('/books')
+        .summary('List all books')
+        .ok(RapiTapir::Types.array(BOOK_SCHEMA))
+        .build
+    ) { BookStore.all }
+
+    # Get published books only (MUST come before /books/:id)
+    endpoint(
+      GET('/books/published')
+        .summary('Get published books')
+        .ok(RapiTapir::Types.array(BOOK_SCHEMA))
+        .build
+    ) { BookStore.all.select { |book| book[:published] } }
+
+    # Get book by ID
+    endpoint(
+      GET('/books/:id')
+        .path_param(:id, RapiTapir::Types.integer)
+        .summary('Get book by ID')
+        .ok(BOOK_SCHEMA)
+        .not_found(RapiTapir::Types.hash({ 'error' => RapiTapir::Types.string }))
+        .build
+    ) do |inputs|
+      book = BookStore.find(inputs[:id])
+      raise ArgumentError, 'Book not found' unless book
+      book
+    end
+
+    # Create new book  
+    endpoint(
+      POST('/books')
+        .summary('Create new book')
+        .json_body(BOOK_CREATE_SCHEMA)
+        .created(BOOK_SCHEMA)
+        .build
+    ) do |inputs|
+      attrs = inputs[:body].transform_keys(&:to_sym)
+      attrs[:published] = true if attrs[:published].nil? # Default to published
+      BookStore.create(attrs)
+    end
+
+    # Update book
+    endpoint(
+      PUT('/books/:id')
+        .path_param(:id, RapiTapir::Types.integer)
+        .json_body(BOOK_CREATE_SCHEMA)
+        .summary('Update book')
+        .ok(BOOK_SCHEMA)
+        .not_found(RapiTapir::Types.hash({ 'error' => RapiTapir::Types.string }))
+        .build
+    ) do |inputs|
+      book = BookStore.find(inputs[:id])
+      raise ArgumentError, 'Book not found' unless book
+      attrs = inputs[:body].transform_keys(&:to_sym)
+      BookStore.update(inputs[:id], attrs)
+    end
+
+    # Delete book
+    endpoint(
+      DELETE('/books/:id')
+        .path_param(:id, RapiTapir::Types.integer)
+        .summary('Delete book')
+        .no_content
+        .not_found(RapiTapir::Types.hash({ 'error' => RapiTapir::Types.string }))
+        .build
+    ) do |inputs|
+      book = BookStore.find(inputs[:id])
+      raise ArgumentError, 'Book not found' unless book
+      BookStore.delete(inputs[:id])
+      '' # Empty content for 204
+    end
+
+    configure :development do
+      puts "\n📚 Bookstore API with SinatraRapiTapir"
+      puts "🚀 Clean syntax: class BookstoreAPI < SinatraRapiTapir" 
+      puts '🌐 Documentation: http://localhost:4567/docs'
+      puts '📋 OpenAPI: http://localhost:4567/openapi.json'
+      puts '❤️  Health: http://localhost:4567/health'
+      puts '📖 Books: http://localhost:4567/books'
+      puts "\n✨ Zero boilerplate, full enterprise features!"
+    end
+  end
+
+  BookstoreAPI.run! if __FILE__ == $PROGRAM_NAME
+else
+  # Demo mode when Sinatra is not available
+  puts "\n📚 RapiTapir Sinatra Extension - Demo Mode"
+  puts '=' * 50
+
+  puts "\n✅ Successfully loaded:"
+  puts '   • RapiTapir core'
+  puts '   • Type system'
+  puts '   • Book schema'
+
+  puts "\n📊 This API would provide:"
+  puts '   GET    /health           - Health check'
+  puts '   GET    /books            - List all books'
+  puts '   GET    /books/:id        - Get book by ID'
+  puts '   POST   /books            - Create new book'
+  puts '   PUT    /books/:id        - Update book'
+  puts '   GET    /books/published  - Published books only'
+  puts '   GET    /docs             - Swagger UI documentation'
+  puts '   GET    /openapi.json     - OpenAPI 3.0 specification'
+
+  puts "\n🎯 Extension features:"
+  puts '   • Zero boilerplate configuration'
+  puts '   • RESTful resource builder (crud block)'
+  puts '   • Built-in authentication helpers'
+  puts '   • Auto-generated OpenAPI documentation'
+  puts '   • Production middleware (CORS, rate limiting, security)'
+  puts '   • Custom endpoints with configure block'
+
+  puts "\n💡 To run the actual server:"
+  puts '   gem install sinatra'
+  puts "   ruby #{__FILE__}"
+
+  puts "\n📖 Sample usage with curl:"
+  puts '   curl http://localhost:4567/books'
+  puts '   curl http://localhost:4567/books/1'
+  puts '   curl -X POST http://localhost:4567/books \\'
+  puts "        -H 'Content-Type: application/json' \\"
+  puts "        -d '{\"title\":\"New Book\",\"author\":\"Author\",\"isbn\":\"123\",\"published\":true}'"
+end

data/examples/hello_world.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# RapiTapir Sinatra Extension - Hello World Example
+#
+# The most minimal example showing how to create a beautiful, type-safe API
+# with automatic OpenAPI documentation in just a few lines of code!
+
+require 'sinatra/base'
+require_relative '../lib/rapitapir'
+
+# Your entire API in under 20 lines! 🚀
+class HelloWorldAPI < SinatraRapiTapir
+
+  # One-line API configuration
+  rapitapir do
+    info(title: 'Hello World API', version: '1.0.0')
+    development_defaults! # Auto CORS, docs, health checks, etc.
+  end
+
+  # Hello World endpoint - beautifully typed and documented using enhanced DSL
+  endpoint(
+    GET('/hello')
+      .query(:name, RapiTapir::Types.optional(RapiTapir::Types.string))
+      .summary('Say hello to someone')
+      .description('Returns a personalized greeting')
+      .tags('Greetings')
+      .ok(RapiTapir::Types.hash({
+        'message' => RapiTapir::Types.string,
+        'timestamp' => RapiTapir::Types.string
+      }))
+      .build
+  ) do |inputs|
+    name = inputs[:name] || 'World'
+    {
+      message: "Hello, #{name}!",
+      timestamp: Time.now.iso8601
+    }
+  end
+
+  # Another endpoint showing path parameters with enhanced DSL
+  endpoint(
+    GET('/greet/:language')
+      .path_param(:language, RapiTapir::Types.string)
+      .summary('Multilingual greeting')
+      .tags('Greetings')
+      .ok(RapiTapir::Types.hash({ 'greeting' => RapiTapir::Types.string }))
+      .build
+  ) do |inputs|
+    greetings = {
+      'english' => 'Hello!',
+      'spanish' => '¡Hola!',
+      'french' => 'Bonjour!',
+      'italian' => 'Ciao!',
+      'german' => 'Hallo!',
+      'japanese' => 'こんにちは!'
+    }
+
+    greeting = greetings[inputs[:language].downcase] || 'Hello!'
+    { greeting: greeting }
+  end
+
+  configure :development do
+    puts "\n🌟 Hello World API with SinatraRapiTapir base class"
+    puts "🚀 Clean syntax: class HelloWorldAPI < SinatraRapiTapir"
+    puts "🌐 Swagger UI:  http://localhost:4567/docs"
+    puts "📋 OpenAPI:     http://localhost:4567/openapi.json"
+    puts "👋 Try it:      http://localhost:4567/hello?name=Developer"
+    puts "🌍 Languages:   http://localhost:4567/greet/spanish"
+    puts "❤️  Health:     http://localhost:4567/health"
+    puts "\n✨ Beautiful, type-safe API in under 15 lines of code!"
+  end
+end
+
+HelloWorldAPI.run! if __FILE__ == $PROGRAM_NAME

data/examples/oauth2/.env.example

@@ -0,0 +1,19 @@
+# Auth0 Configuration for Generic OAuth2 API Testing
+# Copy this to .env and fill in your Auth0 details
+
+# Auth0 Domain (e.g., your-tenant.auth0.com)
+AUTH0_DOMAIN=your-tenant.auth0.com
+
+# Auth0 API Audience (configured in your Auth0 API settings)
+AUTH0_AUDIENCE=https://your-api-identifier
+
+# Auth0 Client ID (for testing with Machine-to-Machine app)
+AUTH0_CLIENT_ID=your-m2m-client-id
+
+# Auth0 Client Secret (for testing with Machine-to-Machine app)
+AUTH0_CLIENT_SECRET=your-m2m-client-secret
+
+# Alternative: OAuth2 Generic Introspection (if not using Auth0)
+# OAUTH2_INTROSPECTION_ENDPOINT=https://your-oauth-server/introspect
+# OAUTH2_CLIENT_ID=your-client-id
+# OAUTH2_CLIENT_SECRET=your-client-secret

data/examples/oauth2/README.md

@@ -0,0 +1,205 @@
+# OAuth2 Examples
+
+This directory contains examples demonstrating OAuth2 integration with RapiTapir.
+
+## Examples
+
+### 1. Songs API with Auth0 (`songs_api_with_auth0.rb`)
+
+A complete example using Auth0 for OAuth2 authentication. Demonstrates:
+
+- Auth0-specific JWT validation with JWKS
+- Scope-based authorization
+- Protected endpoints with different permission levels
+- Comprehensive error handling
+- Rate limiting integration
+
+**Features:**
+- Public endpoints (health check, song list)
+- Protected endpoints requiring authentication
+- Admin endpoints requiring special scopes
+- Token introspection and validation
+- JWKS caching for performance
+
+**Setup:**
+```bash
+# Set Auth0 environment variables
+export AUTH0_DOMAIN="your-tenant.auth0.com"
+export AUTH0_CLIENT_ID="your-client-id"
+export AUTH0_CLIENT_SECRET="your-client-secret"
+export AUTH0_AUDIENCE="your-api-identifier"
+
+# Run the example
+ruby songs_api_with_auth0.rb
+```
+
+### 2. Generic OAuth2 API (`generic_oauth2_api.rb`)
+
+A simpler example using generic OAuth2 token introspection. Demonstrates:
+
+- Token introspection with any OAuth2 provider
+- Basic scope validation
+- User information retrieval
+- Authentication status checking
+
+**Features:**
+- Generic OAuth2 provider support
+- Token introspection endpoint
+- Basic scope-based authorization
+- User context access
+
+**Setup:**
+```bash
+# Set OAuth2 provider environment variables
+export OAUTH2_INTROSPECTION_ENDPOINT="https://your-oauth-server/introspect"
+export OAUTH2_CLIENT_ID="your-client-id"
+export OAUTH2_CLIENT_SECRET="your-client-secret"
+
+# Run the example
+ruby generic_oauth2_api.rb
+```
+
+## Authentication Flow
+
+### Auth0 Example
+1. Client obtains JWT token from Auth0
+2. Client includes token in `Authorization: Bearer <token>` header
+3. RapiTapir validates JWT signature using JWKS
+4. Endpoint handler receives authenticated user context
+
+### Generic OAuth2 Example
+1. Client obtains access token from OAuth2 provider
+2. Client includes token in `Authorization: Bearer <token>` header
+3. RapiTapir introspects token with OAuth2 provider
+4. Endpoint handler receives authenticated user context
+
+## Testing the APIs
+
+### Using curl with Auth0
+
+```bash
+# Get a token (example with Auth0 Client Credentials flow)
+TOKEN=$(curl -s -X POST "https://YOUR_DOMAIN.auth0.com/oauth/token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET", 
+    "audience": "YOUR_API_IDENTIFIER",
+    "grant_type": "client_credentials"
+  }' | jq -r '.access_token')
+
+# Test protected endpoint
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:4567/songs
+```
+
+### Using curl with Generic OAuth2
+
+```bash
+# Assuming you have an access token from your OAuth2 provider
+TOKEN="your-access-token"
+
+# Test protected endpoint
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:4567/tasks
+```
+
+## Available Endpoints
+
+### Songs API (Auth0)
+- `GET /` - Public welcome message
+- `GET /health` - Health check with auth status
+- `GET /songs` - List songs (requires authentication)
+- `POST /songs` - Create song (requires `write:songs` scope)
+- `PUT /songs/:id` - Update song (requires `write:songs` scope)
+- `DELETE /songs/:id` - Delete song (requires `admin:songs` scope)
+- `GET /admin/stats` - Admin statistics (requires `admin:songs` scope)
+
+### Generic OAuth2 API
+- `GET /tasks` - List tasks (public)
+- `GET /health` - Health check with auth status
+- `POST /tasks` - Create task (requires `write` scope)
+- `PUT /tasks/:id` - Update task (requires `write` scope)
+- `DELETE /tasks/:id` - Delete task (requires `admin` scope)
+- `GET /me` - Get user information (requires authentication)
+
+## Documentation
+
+Both examples include automatic OpenAPI documentation:
+- Auth0 Example: http://localhost:4567/docs
+- Generic OAuth2 Example: http://localhost:4567/docs
+
+## Error Handling
+
+Both examples demonstrate comprehensive error handling:
+
+- **401 Unauthorized**: Missing or invalid token
+- **403 Forbidden**: Token valid but insufficient scopes
+- **404 Not Found**: Resource not found
+- **422 Unprocessable Entity**: Invalid request data
+
+## Security Features
+
+- **JWT Validation**: Signature verification and claims validation
+- **Scope Authorization**: Granular permission control
+- **Token Caching**: JWKS and token introspection caching
+- **Rate Limiting**: Built-in rate limiting support
+- **Secure Headers**: Automatic security headers
+- **CORS Support**: Cross-origin resource sharing
+
+## Production Considerations
+
+1. **Environment Variables**: Never hardcode credentials
+2. **HTTPS Only**: Always use HTTPS in production
+3. **Token Expiration**: Handle token refresh properly
+4. **Error Logging**: Log authentication failures securely
+5. **Rate Limiting**: Implement appropriate rate limits
+6. **Monitoring**: Monitor authentication metrics
+
+## Integration Patterns
+
+### Middleware Integration
+```ruby
+# Automatic authentication for all endpoints
+rapitapir do
+  default_auth oauth2_auth(scopes: ['read'])
+end
+```
+
+### Conditional Authentication
+```ruby
+# Different auth requirements per endpoint
+endpoint(
+  GET('/public').build
+) { "Public data" }
+
+endpoint(
+  GET('/private').with_oauth2_auth.build
+) { "Private data" }
+```
+
+### Custom Scope Validation
+```ruby
+# Custom authorization logic
+def admin_required!
+  context = authorize_oauth2!(required_scopes: ['admin'])
+  halt 403 unless context.metadata[:role] == 'admin'
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **JWKS Fetch Errors**: Check Auth0 domain and network connectivity
+2. **Token Validation Failures**: Verify audience and issuer claims
+3. **Scope Mismatches**: Ensure client has required scopes
+4. **Environment Variables**: Double-check all required variables are set
+
+### Debug Mode
+
+Set `RACK_ENV=development` to enable detailed error messages and logging.
+
+### Testing Without OAuth2
+
+Both examples include public endpoints that don't require authentication, useful for testing basic functionality.