funapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d22a926eac2899f60270f0af1b81c694a12bb648249a7d19e6d4ae99e2ef82e8
+  data.tar.gz: 5f4b7f4356379e415fac6cc455deb6d4e147ab55bc7b4df4e202157cb97bce97
+SHA512:
+  metadata.gz: ceb4ad7766b835792450291b431cefeb89fa8cdba7c11b55f2e902bc1fa428dcb78792dc319f99e7a84a206274d8ff197723cfb6d06422729c78a663678716e0
+  data.tar.gz: 30dd76f22965556f0a2c90124426adffb1bba3600c4113341a26efe8cefdddeb2c4e6c68d0e2b196a95533e43b615a5eb5ca0301f8e506189b1b7a0f190029af

data/.claude/25-09-01-OPENAPI_IMPLEMENTATION.md

@@ -0,0 +1,233 @@
+# OpenAPI/Swagger Documentation - Implementation Summary
+
+## ✅ Implementation Complete
+
+FunApi now automatically generates OpenAPI 3.0 specifications from your route definitions and schemas, providing interactive Swagger UI documentation.
+
+## What Was Implemented
+
+### 1. Route Metadata Storage
+- **File**: `lib/fun_api/router.rb`
+- Updated `Route` struct to include metadata field
+- Added `routes` reader to expose routes for spec generation
+- Routes now store: `path_template`, `body_schema`, `query_schema`, `response_schema`
+
+### 2. App-Level Configuration
+- **File**: `lib/fun_api/application.rb`
+- Added OpenAPI config parameters to `App.new`: `title`, `version`, `description`
+- Default values:
+  - title: "FunApi Application"
+  - version: "1.0.0"
+  - description: ""
+
+### 3. Schema Converter
+- **File**: `lib/fun_api/openapi/schema_converter.rb`
+- Converts dry-schema definitions to JSON Schema (OpenAPI compatible)
+- Supports types: `string`, `integer`, `number`, `boolean`, `array`, `object`
+- Handles required vs optional fields
+- Handles array schemas (e.g., `body: [UserSchema]`)
+- Extracts schema names from Ruby constant names
+
+### 4. OpenAPI Spec Generator
+- **File**: `lib/fun_api/openapi/spec_generator.rb`
+- Generates complete OpenAPI 3.0.3 specification
+- Converts path templates: `/users/:id` → `/users/{id}`
+- Generates path parameters from route patterns
+- Generates query parameters from query schemas
+- Generates request body schemas
+- Generates response schemas
+- Populates components/schemas section
+- Excludes internal routes (marked with `internal: true`)
+
+### 5. Documentation Endpoints
+- **Route**: `GET /openapi.json`
+  - Returns the complete OpenAPI specification as JSON
+  - Automatically excluded from the spec itself
+
+- **Route**: `GET /docs`
+  - Serves interactive Swagger UI
+  - Uses CDN-hosted Swagger UI 5.x
+  - Automatically loads spec from `/openapi.json`
+  - Automatically excluded from the spec itself
+
+## Features
+
+### Automatic Schema Detection
+Schemas are automatically detected and named based on Ruby constant names:
+
+```ruby
+UserCreateSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+# Becomes: "UserCreateSchema" in OpenAPI components
+```
+
+### Path Parameters
+Automatically extracted from route patterns:
+
+```ruby
+api.get '/users/:id' do |input, req, task|
+  # Generates OpenAPI path parameter:
+  # {
+  #   "name": "id",
+  #   "in": "path",
+  #   "required": true,
+  #   "schema": { "type": "string" }
+  # }
+end
+```
+
+### Query Parameters
+Generated from query schemas with proper required/optional handling:
+
+```ruby
+QuerySchema = FunApi::Schema.define do
+  optional(:limit).filled(:integer)
+  required(:filter).filled(:string)
+end
+
+api.get '/users', query: QuerySchema do |input, req, task|
+  # Generates query parameters with correct 'required' field
+end
+```
+
+### Request Body
+Supports both single objects and arrays:
+
+```ruby
+# Single object
+api.post '/users', body: UserSchema do
+  # ...
+end
+
+# Array of objects
+api.post '/users/batch', body: [UserSchema] do
+  # Generates: { "type": "array", "items": { "$ref": "..." } }
+end
+```
+
+### Response Schemas
+Automatically documents response structure:
+
+```ruby
+api.get '/users/:id', response_schema: UserOutputSchema do
+  # Documents 200 response with UserOutputSchema structure
+end
+
+api.get '/users', response_schema: [UserOutputSchema] do
+  # Documents 200 response as array of UserOutputSchema
+end
+```
+
+### Type Support
+Fully supports all common JSON Schema types:
+- ✅ `string` - from `.filled(:string)`
+- ✅ `integer` - from `.filled(:integer)` or `.filled(:int)`
+- ✅ `number` - from `.filled(:float)` or `.filled(:decimal)`
+- ✅ `boolean` - from `.filled(:bool)`
+- ✅ `array` - from `.array(:string)`, `.array(:integer)`, etc.
+- ✅ `object` - from `.filled(:hash)`
+
+## Usage Example
+
+```ruby
+require 'fun_api'
+require 'fun_api/server/falcon'
+
+UserCreateSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  optional(:age).filled(:integer)
+end
+
+UserOutputSchema = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+app = FunApi::App.new(
+  title: "User Management API",
+  version: "1.0.0",
+  description: "A simple user management API"
+) do |api|
+  api.get '/users/:id', response_schema: UserOutputSchema do |input, req, task|
+    user = { id: 1, name: 'John', email: 'john@example.com' }
+    [user, 200]
+  end
+
+  api.post '/users', 
+    body: UserCreateSchema, 
+    response_schema: UserOutputSchema do |input, req, task|
+    user = input[:body].merge(id: rand(1000))
+    [user, 201]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 9292)
+```
+
+Then visit:
+- **Swagger UI**: http://localhost:9292/docs
+- **OpenAPI JSON**: http://localhost:9292/openapi.json
+
+## Files Modified/Created
+
+### Modified Files
+1. `lib/fun_api.rb` - Added router require
+2. `lib/fun_api/router.rb` - Added metadata storage
+3. `lib/fun_api/application.rb` - Added OpenAPI config and endpoints
+4. `README.md` - Updated with OpenAPI documentation
+
+### New Files
+1. `lib/fun_api/openapi/schema_converter.rb` - Schema conversion logic
+2. `lib/fun_api/openapi/spec_generator.rb` - OpenAPI spec generation
+3. `test_openapi.rb` - Test application
+4. `OPENAPI_IMPLEMENTATION.md` - This file
+
+## Design Decisions
+
+Following the plan, we implemented:
+
+1. ✅ **Schema names**: Use constant names (e.g., `UserCreateSchema`)
+2. ✅ **Default info**: Use `title`, `version`, `description` from app config
+3. ✅ **Docs path**: Fixed at `/docs`
+4. ✅ **No deduplication**: Each schema reference registered as-is
+5. ✅ **FastAPI-inspired**: Response structure matches FastAPI patterns
+
+## Testing
+
+Run the test application:
+
+```bash
+ruby test_openapi.rb
+```
+
+Then test the endpoints:
+
+```bash
+# Get OpenAPI spec
+curl http://localhost:9292/openapi.json | jq .
+
+# Test actual endpoints
+curl http://localhost:9292/users
+curl -X POST http://localhost:9292/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"John","email":"john@example.com","password":"secret"}'
+```
+
+## Next Steps
+
+Future enhancements could include:
+- Support for additional OpenAPI features (tags, descriptions per route)
+- ReDoc alternative UI at `/redoc`
+- OpenAPI schema validation options
+- Custom response status codes documentation
+- Security scheme definitions
+- Response examples
+
+## Conclusion
+
+The OpenAPI/Swagger documentation generation is fully implemented and working. Users can now get automatic, interactive API documentation by simply defining their routes and schemas, making FunApi truly FastAPI-like in its developer experience.

data/.claude/25-09-05-RESPONSE_SCHEMA.md

@@ -0,0 +1,383 @@
+# Response Schema Feature
+
+## Overview
+
+The `response_schema` feature allows you to validate and filter response data before sending it to clients, similar to FastAPI's `response_model`. This ensures:
+
+1. **Data Security** - Sensitive fields (like passwords) are automatically filtered from responses
+2. **Data Validation** - Responses are validated to ensure your app returns correct data structure
+3. **Documentation** - Response schemas will be used for automatic API documentation generation (future)
+
+## Basic Usage
+
+### Option 1: Using `response_schema` Parameter
+
+```ruby
+# Define input and output schemas
+UserInput = FunApi::Schema.define do
+  required(:username).filled(:string)
+  required(:email).filled(:string)
+  required(:password).filled(:string)
+  optional(:age).filled(:integer)
+end
+
+UserOutput = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:username).filled(:string)
+  required(:email).filled(:string)
+  optional(:age).filled(:integer)
+  # Note: password NOT included
+end
+
+# Use in route
+api.post '/users', 
+  body: UserInput,
+  response_schema: UserOutput do |input, req, task|
+    # Handler returns full user object with password
+    user = {
+      id: 1,
+      username: input[:body][:username],
+      email: input[:body][:email],
+      password: input[:body][:password],  # This will be filtered!
+      age: input[:body][:age]
+    }
+    
+    [user, 201]
+    # Response sent to client:
+    # { "id": 1, "username": "...", "email": "...", "age": ... }
+    # Password is automatically removed!
+end
+```
+
+### Option 2: Return Schema Result Directly
+
+You can also call the schema in your handler and return the result directly:
+
+```ruby
+api.post '/users', body: UserInput do |input, req, task|
+  user_data = {
+    id: 1,
+    username: input[:body][:username],
+    email: input[:body][:email],
+    password: input[:body][:password],
+    age: input[:body][:age]
+  }
+  
+  # Call schema and return result
+  result = UserOutput.call(user_data)
+  [result, 201]
+  # Framework automatically extracts result.to_h
+  # Password is filtered by the schema!
+end
+```
+
+This approach gives you more flexibility in the handler:
+
+```ruby
+api.post '/users', body: UserInput do |input, req, task|
+  user_data = {
+    id: 1,
+    username: input[:body][:username],
+    email: input[:body][:email],
+    password: input[:body][:password],
+    age: input[:body][:age]
+  }
+  
+  # Validate and filter in handler
+  result = UserOutput.call(user_data)
+  
+  # Check if validation succeeded
+  if result.success?
+    [result, 201]
+  else
+    # Handle validation errors
+    raise FunApi::HTTPException.new(
+      status_code: 500,
+      detail: "Invalid response data: #{result.errors.to_h}"
+    )
+  end
+end
+```
+
+### Array Responses
+
+You can use both approaches with arrays too:
+
+```ruby
+ItemSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:price).filled(:float)
+end
+
+# Option 1: Using response_schema parameter
+api.post '/items/batch',
+  body: [ItemSchema],
+  response_schema: [ItemSchema] do |input, req, task|
+    
+  items = input[:body].map do |item_data|
+    {
+      name: item_data[:name],
+      price: item_data[:price],
+      internal_cost: item_data[:price] * 0.5  # This will be filtered!
+    }
+  end
+  
+  [items, 201]
+  # internal_cost is filtered from all items in the response
+end
+
+# Option 2: Return array of schema results
+api.post '/items/batch', body: [ItemSchema] do |input, req, task|
+  results = input[:body].map do |item_data|
+    data = {
+      name: item_data[:name],
+      price: item_data[:price],
+      internal_cost: item_data[:price] * 0.5
+    }
+    ItemSchema.call(data)  # Returns schema result
+  end
+  
+  [results, 201]
+  # Framework converts array of results to array of hashes
+  # internal_cost is filtered by schema
+end
+```
+
+## How It Works
+
+### 1. Request Flow
+
+```
+Request → Input Validation → Handler Execution → Response Validation → Client
+                ↓                                          ↓
+            body/query schema                      response_schema
+            (validates input)                      (validates & filters output)
+```
+
+### 2. Validation Behavior
+
+**For Responses:**
+- ✅ **Missing required fields** → Returns 500 error (your app code is broken)
+- ✅ **Extra fields** → Automatically filtered out (security)
+- ✅ **Wrong types** → Returns 500 error (your app code is broken)
+
+**For Requests (body/query):**
+- ✅ **Missing required fields** → Returns 422 error (client error)
+- ✅ **Wrong types** → Returns 422 error (client error)
+
+### 3. Array Support
+
+Both input validation and response validation support arrays:
+
+```ruby
+# Input array validation
+api.post '/items', body: [ItemSchema] do |input, req, task|
+  # input[:body] is an array of validated hashes
+  items = input[:body].map { |item| create_item(item) }
+  [items, 201]
+end
+
+# Output array validation
+api.get '/items', response_schema: [ItemSchema] do |input, req, task|
+  items = fetch_all_items()  # Returns array
+  [items, 200]  # Each item validated and filtered
+end
+```
+
+## Examples
+
+### Example 1: Filtering Sensitive Data
+
+```ruby
+# Schema with password
+UserWithPassword = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:username).filled(:string)
+  required(:password).filled(:string)
+end
+
+# Public schema without password
+PublicUser = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:username).filled(:string)
+end
+
+api.get '/users/:id', response_schema: PublicUser do |input, req, task|
+  # Fetch from database returns password
+  user = db.fetch_user(input[:path]['id'])
+  # { id: 1, username: "john", password: "hashed_password" }
+  
+  [user, 200]
+  # Client receives: { "id": 1, "username": "john" }
+  # Password automatically filtered!
+end
+```
+
+### Example 2: Batch Operations
+
+```ruby
+CreateUser = FunApi::Schema.define do
+  required(:username).filled(:string)
+  required(:email).filled(:string)
+  required(:password).filled(:string)
+end
+
+UserResponse = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:username).filled(:string)
+  required(:email).filled(:string)
+end
+
+api.post '/users/batch',
+  body: [CreateUser],
+  response_schema: [UserResponse] do |input, req, task|
+    
+  users = input[:body].map do |user_data|
+    create_user(user_data)  # Returns user with password
+  end
+  
+  [users, 201]
+  # All passwords filtered from response array
+end
+```
+
+### Example 3: Optional Response Schema
+
+`response_schema` is optional. If not provided, data is returned as-is:
+
+```ruby
+# Without response_schema - returns all fields
+api.get '/debug/user/:id' do |input, req, task|
+  user = fetch_user(input[:path]['id'])
+  [user, 200]  # Returns everything, including sensitive fields
+end
+
+# With response_schema - filters fields
+api.get '/users/:id', response_schema: UserOutput do |input, req, task|
+  user = fetch_user(input[:path]['id'])
+  [user, 200]  # Filters according to schema
+end
+```
+
+## Error Handling
+
+### Response Validation Errors (500)
+
+If your handler returns data that doesn't match the `response_schema`, a 500 error is returned:
+
+```ruby
+api.get '/users/:id', response_schema: UserOutput do |input, req, task|
+  # Oops! Missing required 'id' field
+  user = { username: "john", email: "john@example.com" }
+  [user, 200]
+end
+
+# Client receives:
+# Status: 500
+# { "detail": "Response validation failed: {id: [\"is missing\"]}" }
+```
+
+This indicates a **bug in your application code** - you promised to return data with certain fields but didn't.
+
+### Input Validation Errors (422)
+
+Input validation errors return 422 (client error):
+
+```ruby
+api.post '/users', body: UserInput do |input, req, task|
+  # ... handler code
+end
+
+# Client sends invalid data:
+# POST /users { "username": "john" }  // missing email
+
+# Response:
+# Status: 422
+# {
+#   "detail": [
+#     {
+#       "loc": ["body", "email"],
+#       "msg": "is missing",
+#       "type": "value_error"
+#     }
+#   ]
+# }
+```
+
+## Best Practices
+
+1. **Choose the right approach**:
+   - Use `response_schema:` parameter when you want automatic validation
+   - Return schema results directly when you need more control or conditional logic
+   - Combine both for maximum safety (schema result + response_schema validation)
+
+2. **Always filter sensitive data** - Use response_schema or schema results to prevent data leaks
+
+3. **Separate input and output schemas** - Often input requires password, output doesn't
+
+4. **Reuse schemas** - Define once, use for both validation and documentation
+
+5. **Use arrays consistently** - `[Schema]` for both input and output arrays
+
+6. **Let validation fail** - Don't catch response validation errors, they indicate bugs
+
+## Implementation Details
+
+### Powered by dry-schema
+
+Both input and response validation use `dry-schema`:
+- Consistent API for defining schemas
+- Automatic type coercion
+- Detailed error messages
+- Built-in validation rules
+
+### Filtering Mechanism
+
+dry-schema automatically filters data:
+```ruby
+# Schema only defines these fields
+schema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+# Data has extra fields
+data = { name: "John", email: "john@example.com", password: "secret", admin: true }
+
+# Calling schema.call(data).to_h returns:
+# { name: "John", email: "john@example.com" }
+# Extra fields automatically removed!
+```
+
+### Schema Result Detection
+
+When you return a `Dry::Schema::Result` object, the framework automatically detects it and extracts the hash:
+
+```ruby
+# Handler returns schema result
+api.post '/users' do |input, req, task|
+  result = UserOutput.call(user_data)
+  [result, 201]  # Returns Dry::Schema::Result
+end
+
+# Framework checks:
+# 1. Is payload a Dry::Schema::Result? Yes
+# 2. Extract: result.to_h
+# 3. Send filtered hash to client
+
+# Works with arrays too:
+api.post '/users/batch' do |input, req, task|
+  results = users.map { |u| UserOutput.call(u) }
+  [results, 201]  # Array of Dry::Schema::Result
+end
+
+# Framework maps each result to .to_h automatically
+```
+
+## Future Enhancements
+
+- OpenAPI/Swagger documentation generation from schemas
+- `response_schema_exclude_unset` option (exclude default values)
+- `response_schema_include/exclude` options for field filtering
+- Response streaming support
+- Content negotiation (JSON, XML, etc.)