如何在FastAPI动态创建端点时通过add_api_route添加openapi_examples？

要给动态创建的FastAPI端点添加OpenAPI示例，你可以通过以下几种方式实现：

1. 直接在Pydantic模型中定义示例 #

如果每个端点对应的model是Pydantic的BaseModel子类，你可以直接在模型的Config类中定义示例，FastAPI会自动将其纳入OpenAPI schema：

from pydantic import BaseModel

class ModelA(BaseModel):
    param1: str
    param2: int

    class Config:
        # 单个示例
        example = {"param1": "测试值", "param2": 42}
        # 多个示例（符合OpenAPI规范格式）
        examples = {
            "示例1": {"summary": "基础请求", "value": {"param1": "hello", "param2": 1}},
            "示例2": {"summary": "带特殊值的请求", "value": {"param1": "world", "param2": 100}}
        }

这种方式适合每个模型对应固定示例的场景，无需额外修改路由创建逻辑。

2. 通过openapi_extra动态注入示例 #

如果需要为每个端点动态配置不同的示例（比如从Endpoint实例传递），可以利用FastAPIadd_api_route方法的openapi_extra参数，手动注入OpenAPI规范的示例内容：

步骤1：更新Endpoint类，添加示例字段 #

from pydantic import BaseModel, BaseSettings
from typing import Type, Dict, Any

class Endpoint(BaseSettings):
    model: Type[BaseModel]  # 明确为Pydantic模型类型
    name: str
    template: str
    examples: Dict[str, Dict] | None = None  # 新增示例字段，存储多组示例

步骤2：修正端点函数的参数类型 #

确保端点函数的参数使用对应模型，让FastAPI能正确生成请求体schema：

def create_endpoint(p: Endpoint):
    async def endpoint(parameters: p.model):  # 使用当前Endpoint实例的model作为参数类型
        logger.info(
            f"Request to {p.name} product",
            parameters=parameters.dict()  # 替换为你的export()方法
        )
        payload = preprocess(name=p.name, parameters=parameters.dict())
        logger.info("payload", payload=payload.model_dump())
        return await submit_process(payload)

    return endpoint

步骤3：添加路由时注入示例 #

在循环创建路由时，通过openapi_extra传递示例到OpenAPI schema：

for p in products:  # 注意原代码中变量名是products，不是endpoints
    openapi_extra = {}
    if p.examples:
        # 为请求体添加示例
        openapi_extra["requestBody"] = {
            "content": {
                "application/json": {
                    "examples": p.examples
                }
            }
        }
    
    router.add_api_route(
        f"/endpoints/{p.name}", 
        create_endpoint(p), 
        tags=["endpoint"], 
        methods=["POST"],
        openapi_extra=openapi_extra
    )

步骤4：定义带示例的Endpoint实例 #

products: list[Endpoint] = [
    Endpoint(
        model=ModelA,
        name="a",
        template="a",
        examples={
            "示例1": {"summary": "A接口基础请求", "value": {"param1": "test_a", "param2": 42}},
            "示例2": {"summary": "A接口特殊场景请求", "value": {"param1": "special_a", "param2": 999}}
        }
    ),
    Endpoint(
        model=ModelB,
        name="b",
        template="b",
        examples={
            "示例1": {"summary": "B接口请求", "value": {"x": "test_b", "y": True}}
        }
    ),
]

3. 为响应添加示例（可选） #

如果需要为响应添加示例，同样可以在openapi_extra中扩展responses字段：

openapi_extra["responses"] = {
    200: {
        "description": "成功响应",
        "content": {
            "application/json": {
                "examples": {
                    "响应示例": {"summary": "成功返回结果", "value": {"status": "success", "data": "result"}}
                }
            }
        }
    }
}

内容的提问来源于stack exchange，提问作者tonystark1234