Complete middleware reference and openapi-docs chapter

Author: Folyd

docs/guide/web/_meta.json

@@ -2,7 +2,6 @@
     "route",
     "validator",
     "response",
-    "middleware",
     "openapi-docs",
     "configuration",
     "project"

docs/guide/web/middleware.md

@@ -1,2 +1,207 @@
 # OpenAPI and Docs
 
+AIScript provides automatic OpenAPI documentation generation from your route definitions with zero configuration. This feature creates comprehensive API documentation including type information, validation rules, and examples derived directly from your code.
+
+## Basic Documentation
+
+The simplest way to document your API is through docstrings. In AIScript, you can use triple-quoted strings (`"""..."""`) to provide documentation for routes and their parameters:
+
+```py
+post /api/chat {
+    """
+    Chat API endpoint
+    
+    Sends a message to the chat service and returns a response.
+    """
+
+    body {
+        """The message to be sent to the chat service"""
+        message: str,
+    }
+
+    return "Input: " + body.message + "!";
+}
+```
+
+## Documenting Routes
+
+Each route can have a detailed description:
+
+```py
+get /api/users {
+    """
+    List all users
+    
+    Returns a paginated list of all users in the system.
+    Results can be filtered by role or status.
+    """
+    
+    query {
+        @number(min=1)
+        """Page number for pagination"""
+        page: int = 1,
+        
+        @number(min=1, max=100)
+        """Number of items per page"""
+        limit: int = 20
+    }
+    
+    // Route implementation
+}
+```
+
+## Documenting Parameters
+
+You can document query parameters, path parameters, and request body fields:
+
+### Query Parameters
+
+```py
+get /api/products {
+    query {
+        """Filter products by category"""
+        category: str,
+        
+        """Sort order (asc or desc)"""
+        @in(["asc", "desc"])
+        sort: str = "asc",
+        
+        """Minimum price filter"""
+        @number(min=0)
+        min_price: float
+    }
+}
+```
+
+### Path Parameters
+
+```py
+get /api/users/<id:int> {
+    """
+    Get user by ID
+    
+    Retrieves detailed information about a specific user.
+    
+    Parameters:
+      id: The unique identifier of the user
+    """
+    
+    // Route implementation
+}
+```
+
+### Request Body
+
+```py
+post /api/products {
+    @json
+    body {
+        """Product name (must be unique)"""
+        @string(min_len=3, max_len=100)
+        name: str,
+        
+        """Detailed product description"""
+        description: str,
+        
+        """Product price in USD"""
+        @number(min=0.01)
+        price: float,
+        
+        """Product categories (at least one required)"""
+        @array(min_items=1)
+        categories: array
+    }
+}
+```
+
+## Response Documentation
+
+You can document the responses a route might return:
+
+```py
+get /api/orders/<id:int> {
+    """
+    Get order details
+    
+    Retrieves the details of a specific order.
+    
+    Responses:
+      200: Successful operation
+      404: Order not found
+      403: Unauthorized access
+    """
+    
+    // Route implementation
+}
+```
+
+## Auto-Generated Documentation
+
+AIScript automatically generates OpenAPI documentation based on your route definitions. This documentation includes:
+
+1. All routes and their HTTP methods
+2. Request parameters (query, path, body)
+3. Validation rules applied to parameters
+4. Data types for all parameters and responses
+5. Docstrings as descriptions
+6. Documentation specific to each parameter
+
+## Accessing Documentation
+
+By default, AIScript makes your API documentation available at `/redoc` and the OpenAPI specification at `/openapi.json`. You can customize these paths in your project configuration:
+
+```toml
+# project.toml
+
+[apidoc]
+enabled = true
+type = "redoc"
+path = "/redoc"
+```
+
+AIScript's documentation UI support **Swagger UI** and **Redoc**.
+
+## Tags and Grouping
+
+You can use tags to group related endpoints in the documentation:
+
+```py
+@docs(tag = "Users")
+get /api/users {
+    """List all users"""
+}
+
+@docs(tag = "Users")
+get /api/users/<id:int> {
+    """Get user by ID"""
+}
+
+@docs(tag = "Users")
+get /api/products {
+    """List all products"""
+}
+```
+
+## Hiding Endpoints
+
+You can exclude specific endpoints from documentation:
+
+```py
+@docs(hidden=true)
+get /internal/metrics {
+    """This endpoint won't appear in documentation"""
+}
+```
+
+## Benefits
+
+Automatic OpenAPI documentation in AIScript offers several benefits:
+
+1. **Zero configuration**: Documentation is generated automatically from your code
+2. **Always up-to-date**: Documentation updates whenever your code changes
+3. **Complete type information**: All parameter types are accurately reflected
+4. **Validation rules included**: All validators are documented
+5. **Interactive testing**: Test endpoints directly from the documentation UI
+6. **Client generation**: Use the OpenAPI spec to generate client libraries in various languages
+
+AIScript's built-in documentation system ensures your API is well-documented with minimal effort, making it easier for both you and your API consumers to understand and use your services.

docs/guide/web/openapi-docs.md

@@ -1,3 +1,5 @@
+# AI
+
 > For AI observability, please refer to [observability](./observability.md).
 
 ```toml

docs/reference/configuration/ai.md

@@ -1,3 +1,5 @@
+# Auth
+
 ```toml
 [auth.jwt]
 secret = "$JWT_SECRET"

docs/reference/configuration/auth.md

@@ -1,3 +1,5 @@
+# Database
+
 ```toml
 [database.pinecone]
 api_key = "YOUR_API_KEY"

docs/reference/configuration/database.md

@@ -1,3 +1,4 @@
+# General
 
 ```toml
 [project]

docs/reference/configuration/general.md

@@ -1,28 +1,128 @@
+# Middleware
+
+Middleware in AIScript provides a powerful way to process HTTP requests and responses. Middleware functions are executed in a sequence, allowing you to modify requests, validate authentication, log activities, and more before a route handler is invoked.
+
+## CORS
+
+Controls Cross-Origin Resource Sharing settings.
 
 ```toml
+# project.toml
+
 [middleware.cors]
-allowed_origins = ["http://localhost:3000"]
+allowed_origins = ["http://localhost:3000", "https://example.com"]
 allowed_methods = ["GET", "POST", "PUT", "DELETE"]
 allowed_headers = ["Content-Type", "Authorization"]
 allow_credentials = true
+max_age = 86400
+```
 
-[middleware.body_limit]
-limit = "100KB"
+### Options
+
+| Option              | Type    | Description                                               | Default                                       |
+| ------------------- | ------- | --------------------------------------------------------- | --------------------------------------------- |
+| `allowed_origins`   | Array   | List of origins that are allowed to access the resource   | `["*"]`                                       |
+| `allowed_methods`   | Array   | HTTP methods allowed                                      | `["GET", "POST", "PUT", "DELETE", "OPTIONS"]` |
+| `allowed_headers`   | Array   | HTTP headers allowed                                      | `["Content-Type", "Authorization"]`           |
+| `allow_credentials` | Boolean | Indicates if cookies can be included in requests          | `false`                                       |
+| `max_age`           | Number  | How long the results of a preflight request can be cached | `86400` (24 hours)                            |
+
+## Rate Limit
+
+Limits the number of requests a client can make within a specified time period.
+
+```toml
+# project.toml
 
 [middleware.rate_limit]
-enabled = true
-max_requests = 100
-window = 60
+limit = 100
+window = 60  # in seconds
+message = "Too many requests, please try again later."
+```
+
+### Options
+
+| Option          | Type   | Description                                                             | Default               |
+| --------------- | ------ | ----------------------------------------------------------------------- | --------------------- |
+| `limit`         | Number | Maximum number of requests allowed                                      | `100`                 |
+| `window`        | Number | Time window in seconds                                                  | `60`                  |
+| `message`       | String | Message to return when rate limit is exceeded                           | `"Too many requests"` |
+| `key_extractor` | String | Function to extract the rate limit key (e.g., "ip", "header:X-API-Key") | `"ip"`                |
+
+## Body Limit
+
+Limits the size of request bodies.
+
+```toml
+# project.toml
+
+[middleware.body_limit]
+limit = "1mb"
+```
+
+### Options
+
+| Option  | Type   | Description                                         | Default |
+| ------- | ------ | --------------------------------------------------- | ------- |
+| `limit` | String | Maximum size of request body (e.g., "1mb", "500kb") | `"1mb"` |
+
+## Timeout
+
+Sets a timeout for handling requests.
+
+```toml
+# project.toml
 
 [middleware.timeout]
-timeout = 5
+duration = 5000  # in milliseconds
+message = "Request timeout"
+```
+
+### Options
+
+| Option     | Type   | Description                           | Default             |
+| ---------- | ------ | ------------------------------------- | ------------------- |
+| `duration` | Number | Timeout in milliseconds               | `5000`              |
+| `message`  | String | Message to return when timeout occurs | `"Request timeout"` |
+
+## Compression
+
+Compresses response bodies.
 
+```toml
+# project.toml
+
+[middleware.compression]
+level = 6  # compression level (1-9)
+threshold = 1024  # minimum size to compress
 ```
 
-## CORS
+### Options
 
-## Body limit
+| Option      | Type   | Description                       | Default                                                              |
+| ----------- | ------ | --------------------------------- | -------------------------------------------------------------------- |
+| `level`     | Number | Compression level (1-9)           | `6`                                                                  |
+| `threshold` | Number | Minimum size in bytes to compress | `1024`                                                               |
+| `types`     | Array  | Content types to compress         | `["text/plain", "text/html", "application/json", "application/xml"]` |
 
-## Rate Limit
+## Security Headers
 
-## Timeout
+Adds security-related HTTP headers to responses.
+
+```toml
+# project.toml
+
+[middleware.security_headers]
+xss_protection = "1; mode=block"
+content_security_policy = "default-src 'self'"
+```
+
+### Options
+
+| Option                    | Type   | Description                          | Default                        |
+| ------------------------- | ------ | ------------------------------------ | ------------------------------ |
+| `xss_protection`          | String | X-XSS-Protection header value        | `"1; mode=block"`              |
+| `content_type_options`    | String | X-Content-Type-Options header value  | `"nosniff"`                    |
+| `frame_options`           | String | X-Frame-Options header value         | `"SAMEORIGIN"`                 |
+| `content_security_policy` | String | Content-Security-Policy header value | `"default-src 'self'"`         |
+| `referrer_policy`         | String | Referrer-Policy header value         | `"no-referrer-when-downgrade"` |