Schema Extra Examples

Provide example data for API documentation and testing.

Pydantic Model Examples

Use model_config with json_schema_extra to add examples:

from pydantic import BaseModel, Field
from evoid.web.route import Service, post

class User(BaseModel):
    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "name": "John Doe",
                    "email": "john@example.com",
                    "age": 30,
                    "is_active": True
                }
            ]
        }
    }
    
    name: str
    email: str
    age: int = Field(ge=0, le=150)
    is_active: bool = True

app = Service("api")

@app.post("/users/")
async def create_user(user: User):
    return {"status": "created", "user": user.model_dump()}

Field-Level Examples

Add examples to individual fields:

from pydantic import BaseModel, Field
from evoid.web.route import Service, post

class Product(BaseModel):
    name: str = Field(
        examples=["Wireless Mouse"],
        description="Product name"
    )
    price: float = Field(
        gt=0,
        examples=[29.99],
        description="Price in USD"
    )

app = Service("api")

@app.post("/products/")
async def create_product(product: Product):
    return product.model_dump()

Intent Metadata Examples

In native IOP, attach examples to intent metadata:

from evoid.native import create_service, on
from evoid import Intent, Level

app = create_service("api")

CREATE_USER = Intent(
    name="POST:/users",
    level=Level.STANDARD,
    metadata={
        "method": "POST",
        "path": "/users",
        "examples": [
            {
                "description": "Create a new user",
                "request": {
                    "name": "Jane Smith",
                    "email": "jane@example.com",
                    "age": 25
                },
                "response": {
                    "status": "created",
                    "user_id": 123
                }
            }
        ]
    },
)

async def handle_create_user(intent: Intent) -> dict:
    body = intent.metadata.get("body", {})
    return {
        "status": "created",
        "user_id": 123,
        "name": body.get("name")
    }

on(app, CREATE_USER, handle_create_user)

Summary