funapi 0.1.0

data/docs-site/content/essential/openapi.md

@@ -0,0 +1,155 @@
+---
+title: OpenAPI
+---
+
+# OpenAPI
+
+FunApi automatically generates OpenAPI 3.0 documentation from your routes and schemas.
+
+## Built-in Endpoints
+
+Every FunApi application exposes:
+
+| Endpoint | Description |
+|----------|-------------|
+| `/docs` | Interactive Swagger UI |
+| `/openapi.json` | Raw OpenAPI specification |
+
+## Configuring Your API
+
+Set API metadata when creating the app:
+
+```ruby
+app = FunApi::App.new(
+  title: "User Management API",
+  version: "1.0.0",
+  description: "A comprehensive user management system"
+) do |api|
+  # routes...
+end
+```
+
+This appears in the OpenAPI spec and Swagger UI header.
+
+## What Gets Documented
+
+### Routes
+
+All routes are automatically included:
+
+```ruby
+api.get '/users' do |input, req, task|
+  # Documented as GET /users
+end
+
+api.post '/users' do |input, req, task|
+  # Documented as POST /users
+end
+```
+
+### Path Parameters
+
+Path parameters are extracted and documented:
+
+```ruby
+api.get '/users/:id' do |input, req, task|
+  # Documented with {id} parameter
+end
+```
+
+### Schemas
+
+Schemas become OpenAPI components:
+
+```ruby
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+api.post '/users', body: UserSchema do |input, req, task|
+  # Request body documented with UserSchema
+end
+```
+
+### Response Schemas
+
+Response schemas document the output:
+
+```ruby
+api.get '/users/:id', response_schema: UserOutputSchema do |input, req, task|
+  # Response documented with UserOutputSchema
+end
+```
+
+## Swagger UI
+
+The `/docs` endpoint serves an interactive Swagger UI where you can:
+
+- Browse all endpoints
+- See request/response schemas
+- Try out API calls directly
+- View example payloads
+
+## OpenAPI JSON
+
+Access the raw spec at `/openapi.json`:
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "User Management API",
+    "version": "1.0.0",
+    "description": "A comprehensive user management system"
+  },
+  "paths": {
+    "/users": {
+      "get": { ... },
+      "post": { ... }
+    }
+  },
+  "components": {
+    "schemas": {
+      "UserSchema": { ... }
+    }
+  }
+}
+```
+
+## Schema Names
+
+Schema names in OpenAPI come from your Ruby constant names:
+
+```ruby
+UserCreateSchema = FunApi::Schema.define { ... }
+# Becomes "UserCreateSchema" in OpenAPI
+
+UserOutputSchema = FunApi::Schema.define { ... }
+# Becomes "UserOutputSchema" in OpenAPI
+```
+
+## Use Cases
+
+### Client Generation
+
+Use the OpenAPI spec to generate clients:
+
+```bash
+# Generate TypeScript client
+npx openapi-typescript http://localhost:3000/openapi.json -o api.ts
+
+# Generate Python client
+openapi-generator generate -i http://localhost:3000/openapi.json -g python
+```
+
+### API Testing
+
+Import the spec into Postman, Insomnia, or other API tools.
+
+### Documentation Hosting
+
+Export the spec and host on platforms like:
+- SwaggerHub
+- Redoc
+- Stoplight

data/docs-site/content/essential/routing.md

@@ -0,0 +1,123 @@
+---
+title: Routing
+---
+
+# Routing
+
+Routes map HTTP requests to handler functions based on the path and method.
+
+## Defining Routes
+
+FunApi provides methods for each HTTP verb:
+
+```ruby
+api.get '/users' do |input, req, task|
+  [{ users: [] }, 200]
+end
+
+api.post '/users' do |input, req, task|
+  [{ created: input[:body] }, 201]
+end
+
+api.put '/users/:id' do |input, req, task|
+  [{ updated: true }, 200]
+end
+
+api.patch '/users/:id' do |input, req, task|
+  [{ patched: true }, 200]
+end
+
+api.delete '/users/:id' do |input, req, task|
+  [{}, 204]
+end
+```
+
+## Path Parameters
+
+Capture dynamic segments with `:param` syntax:
+
+```ruby
+api.get '/users/:id' do |input, req, task|
+  user_id = input[:path]['id']  # Always a string
+  [{ id: user_id }, 200]
+end
+
+api.get '/posts/:post_id/comments/:comment_id' do |input, req, task|
+  post_id = input[:path]['post_id']
+  comment_id = input[:path]['comment_id']
+  [{ post_id: post_id, comment_id: comment_id }, 200]
+end
+```
+
+> **Note**: Path parameters are always strings. Convert them manually if needed:
+> ```ruby
+> id = input[:path]['id'].to_i
+> ```
+
+## Query Parameters
+
+Query parameters come from the URL query string:
+
+```ruby
+# GET /search?q=ruby&limit=10
+api.get '/search' do |input, req, task|
+  query = input[:query][:q]
+  limit = input[:query][:limit]&.to_i || 20
+  [{ query: query, limit: limit }, 200]
+end
+```
+
+With validation:
+
+```ruby
+SearchSchema = FunApi::Schema.define do
+  required(:q).filled(:string)
+  optional(:limit).filled(:integer)
+  optional(:offset).filled(:integer)
+end
+
+api.get '/search', query: SearchSchema do |input, req, task|
+  # input[:query] is validated and coerced
+  [{ results: search(input[:query]) }, 200]
+end
+```
+
+## Request Body
+
+POST, PUT, and PATCH routes typically receive a JSON body:
+
+```ruby
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+api.post '/users', body: UserSchema do |input, req, task|
+  user = input[:body]  # Validated hash
+  [{ created: user }, 201]
+end
+```
+
+## Route Priority
+
+Routes are matched in the order they're defined. More specific routes should come first:
+
+```ruby
+api.get '/users/me' do |input, req, task|
+  # Matches /users/me
+end
+
+api.get '/users/:id' do |input, req, task|
+  # Matches /users/123, /users/anything
+end
+```
+
+## The Root Route
+
+The root path `/` works like any other route:
+
+```ruby
+api.get '/' do |input, req, task|
+  [{ status: 'ok' }, 200]
+end
+```

data/docs-site/content/essential/validation.md

@@ -0,0 +1,166 @@
+---
+title: Validation
+---
+
+# Validation
+
+FunApi uses [dry-schema](https://dry-rb.org/gems/dry-schema/) for request and response validation.
+
+## Defining Schemas
+
+Create schemas with `FunApi::Schema.define`:
+
+```ruby
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  optional(:age).filled(:integer)
+  optional(:role).filled(:string)
+end
+```
+
+> **Technical Detail**: `FunApi::Schema.define` is a thin wrapper around `Dry::Schema.Params`. You have access to the full dry-schema DSL.
+
+## Applying Schemas
+
+### Body Validation
+
+```ruby
+api.post '/users', body: UserSchema do |input, req, task|
+  user = input[:body]  # Validated and coerced
+  [{ created: user }, 201]
+end
+```
+
+### Query Validation
+
+```ruby
+SearchSchema = FunApi::Schema.define do
+  required(:q).filled(:string)
+  optional(:limit).filled(:integer)
+  optional(:offset).filled(:integer)
+end
+
+api.get '/search', query: SearchSchema do |input, req, task|
+  [{ results: search(input[:query]) }, 200]
+end
+```
+
+### Response Validation
+
+Filter and validate response data:
+
+```ruby
+UserOutputSchema = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+api.get '/users/:id', response_schema: UserOutputSchema do |input, req, task|
+  user = find_user(input[:path]['id'])
+  # password and other fields are filtered out
+  [user, 200]
+end
+```
+
+## Schema DSL
+
+### Required vs Optional
+
+```ruby
+FunApi::Schema.define do
+  required(:name).filled(:string)   # Must be present and non-empty
+  optional(:nickname).filled(:string)  # Can be absent, but if present must be valid
+end
+```
+
+### Types
+
+```ruby
+FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:age).filled(:integer)
+  required(:price).filled(:float)
+  required(:active).filled(:bool)
+  required(:tags).filled(:array)
+  required(:metadata).filled(:hash)
+end
+```
+
+### Nested Objects
+
+```ruby
+AddressSchema = FunApi::Schema.define do
+  required(:street).filled(:string)
+  required(:city).filled(:string)
+  required(:zip).filled(:string)
+end
+
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:address).hash(AddressSchema)
+end
+```
+
+### Arrays of Objects
+
+```ruby
+ItemSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:quantity).filled(:integer)
+end
+
+OrderSchema = FunApi::Schema.define do
+  required(:items).array(:hash) do
+    required(:name).filled(:string)
+    required(:quantity).filled(:integer)
+  end
+end
+```
+
+Or validate an array of items:
+
+```ruby
+api.post '/users/batch', body: [UserSchema] do |input, req, task|
+  users = input[:body]  # Array of validated users
+  [{ created: users.length }, 201]
+end
+```
+
+## Validation Errors
+
+When validation fails, FunApi returns a FastAPI-style error response:
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "email"],
+      "msg": "is missing",
+      "type": "value_error"
+    },
+    {
+      "loc": ["body", "age"],
+      "msg": "must be an integer",
+      "type": "value_error"
+    }
+  ]
+}
+```
+
+Status code: `422 Unprocessable Entity`
+
+## Custom Validation
+
+For complex validation, use dry-schema's full DSL:
+
+```ruby
+UserSchema = FunApi::Schema.define do
+  required(:email).filled(:string, format?: /@/)
+  required(:age).filled(:integer, gt?: 0, lt?: 150)
+  required(:password).filled(:string, min_size?: 8)
+end
+```
+
+See the [dry-schema documentation](https://dry-rb.org/gems/dry-schema/) for the complete DSL reference.

data/docs-site/content/getting-started/at-glance.md

@@ -0,0 +1,82 @@
+---
+title: At Glance
+---
+
+# At Glance
+
+## What is FunApi?
+
+FunApi is a minimal, async-first Ruby web framework for building APIs. It draws heavy inspiration from Python's FastAPI, bringing that same developer experience to Ruby.
+
+## Philosophy
+
+<!-- 
+TODO: Fill in your philosophy here. Some prompts:
+- Why did you create this?
+- What's wrong with existing Ruby frameworks for APIs?
+- What makes async-first important?
+- Who is this for?
+-->
+
+### Async-first
+
+FunApi is built from the ground up for async operations. Every route handler receives an `Async::Task` that enables true concurrent execution within your routes.
+
+### Minimal Magic
+
+Unlike larger frameworks, FunApi keeps things explicit. No hidden callbacks, no implicit behavior. You see exactly what's happening.
+
+### Validation at the Edges
+
+Request validation happens before your handler runs. Response filtering happens after. Your business logic stays clean.
+
+### Auto-Documentation
+
+Your API documentation is generated from your code. Define a schema once, get validation AND documentation.
+
+## Where FunApi Fits
+
+<!-- 
+TODO: Fill in comparison with other Ruby frameworks:
+- vs Rails API-only
+- vs Sinatra
+- vs Roda
+- vs Grape
+-->
+
+| Framework | Use Case | FunApi Difference |
+|-----------|----------|-------------------|
+| Rails API | Full-featured API | FunApi is lighter, async-first |
+| Sinatra | Simple APIs | FunApi adds validation, OpenAPI |
+| Roda | Routing-focused | FunApi is async, has schemas |
+| Grape | API-focused | FunApi is simpler, async |
+
+## Core Concepts Preview
+
+```ruby
+app = FunApi::App.new do |api|
+  # Validation schemas
+  UserSchema = FunApi::Schema.define do
+    required(:name).filled(:string)
+  end
+
+  # Routes with validation
+  api.post '/users', body: UserSchema do |input, req, task|
+    # input[:body] is already validated
+    [{ user: input[:body] }, 201]
+  end
+
+  # Async operations
+  api.get '/dashboard/:id' do |input, req, task|
+    # Concurrent fetches
+    user = task.async { fetch_user(input[:path]['id']) }
+    posts = task.async { fetch_posts(input[:path]['id']) }
+    
+    [{ user: user.wait, posts: posts.wait }, 200]
+  end
+
+  # Lifecycle hooks
+  api.on_startup { DB.connect }
+  api.on_shutdown { DB.disconnect }
+end
+```

data/docs-site/content/getting-started/key-concepts.md

@@ -0,0 +1,150 @@
+---
+title: Key Concepts
+---
+
+# Key Concepts
+
+Understanding these core concepts will help you work effectively with FunApi.
+
+## The App
+
+Everything starts with `FunApi::App`. It's your application container that holds routes, middleware, and configuration.
+
+```ruby
+app = FunApi::App.new(
+  title: "My API",        # Shows in OpenAPI docs
+  version: "1.0.0",       # API version
+  description: "..."      # Optional description
+) do |api|
+  # Define routes here
+end
+```
+
+## Route Handlers
+
+Route handlers are blocks that receive three arguments:
+
+```ruby
+api.get '/path' do |input, req, task|
+  # input - Hash with :path, :query, :body
+  # req   - Rack::Request object
+  # task  - Async::Task for concurrent operations
+  
+  [response_data, status_code]
+end
+```
+
+### The Input Hash
+
+All request data is normalized into a single `input` hash:
+
+```ruby
+api.post '/users/:id' do |input, req, task|
+  input[:path]   # => { 'id' => '123' }
+  input[:query]  # => { limit: 10, offset: 0 }
+  input[:body]   # => { name: 'Alice', ... }
+end
+```
+
+### Return Value
+
+Handlers return a tuple of `[data, status_code]`:
+
+```ruby
+[{ user: user }, 200]        # Success
+[{ error: 'Not found' }, 404] # Error
+[created_user, 201]          # Created
+```
+
+## Schemas
+
+Schemas define the shape of request and response data using dry-schema:
+
+```ruby
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  optional(:age).filled(:integer)
+end
+```
+
+Apply schemas to routes:
+
+```ruby
+api.post '/users', body: UserSchema do |input, req, task|
+  # input[:body] is validated and coerced
+end
+
+api.get '/users', query: QuerySchema do |input, req, task|
+  # input[:query] is validated
+end
+```
+
+## Async Task
+
+The `task` parameter is an `Async::Task` from Ruby's Async library. Use it for concurrent operations:
+
+```ruby
+api.get '/dashboard' do |input, req, task|
+  # These run concurrently
+  user_task = task.async { fetch_user }
+  posts_task = task.async { fetch_posts }
+  stats_task = task.async { fetch_stats }
+
+  # Wait for all to complete
+  [{
+    user: user_task.wait,
+    posts: posts_task.wait,
+    stats: stats_task.wait
+  }, 200]
+end
+```
+
+## Middleware Stack
+
+Middleware wraps your application, processing requests before they reach handlers and responses after:
+
+```ruby
+app = FunApi::App.new do |api|
+  # Built-in middleware
+  api.add_cors(allow_origins: ['*'])
+  api.add_request_logger
+  
+  # Standard Rack middleware
+  api.use Rack::Session::Cookie, secret: 'key'
+  
+  # Routes...
+end
+```
+
+Middleware runs in order: first added runs first.
+
+## Lifecycle Hooks
+
+Run code when the application starts or stops:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.on_startup do
+    DB.connect
+    Cache.warm
+  end
+
+  api.on_shutdown do
+    DB.disconnect
+  end
+end
+```
+
+## OpenAPI/Swagger
+
+FunApi automatically generates OpenAPI documentation from your routes and schemas:
+
+- `/docs` - Interactive Swagger UI
+- `/openapi.json` - Raw OpenAPI specification
+
+The docs are generated from:
+- Route paths and methods
+- Path parameters
+- Query and body schemas
+- Response schemas