如何为FastAPI的Form输入生成Swagger UI请求示例？

当然可以！给Form类型输入加请求示例不需要依赖Pydantic模型，直接在Form()参数里用example或examples就能实现，下面给你两种场景的实现方式：

单个字段示例 #

如果只需要给每个Form字段设置一个默认示例，直接在Form()里添加example参数即可：

from fastapi import FastAPI, Form

app = FastAPI()

@app.post("/submit-form/")
async def submit_form(
    username: str = Form(..., example="john_doe"),
    email: str = Form(..., example="john@example.com"),
    age: int = Form(..., example=30)
):
    return {"username": username, "email": email, "age": age}

启动服务后打开Swagger UI，每个Form字段会自动显示你设置的示例值，测试请求时可以直接使用或修改。

多个字段示例 #

如果需要给单个Form字段提供多个可选示例，用examples参数，格式要符合OpenAPI规范：

from fastapi import FastAPI, Form
from typing import Annotated

app = FastAPI()

@app.post("/submit-form-multiple/")
async def submit_form_multiple(
    username: Annotated[str, Form(
        ...,
        examples={
            "普通用户": {"summary": "常规账号", "value": "john_doe"},
            "管理员": {"summary": "后台账号", "value": "admin_zhang"}
        }
    )],
    email: Annotated[str, Form(
        ...,
        examples={
            "个人邮箱": {"summary": "普通邮箱", "value": "john@example.com"},
            "企业邮箱": {"summary": "工作邮箱", "value": "admin@company.cn"}
        }
    )]
):
    return {"username": username, "email": email}

这种方式下，Swagger UI里每个字段会出现下拉选项，你可以选择不同的示例值填充到表单中。

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