如何保留Optional类型提示让FastAPI生成合规的OpenAPI 3.0.1规范？

你可以通过以下两种方式实现，既保留代码中的Optional类型提示，又让FastAPI生成符合OpenAPI 3.0.x要求的规范（用nullable: true替代type: null的anyOf结构）：

1. 局部处理：针对单个查询参数/模型字段 #

查询参数场景 #

在Annotated中同时保留Optional类型，并给Query添加nullable=True参数。这样类型提示依然清晰，同时FastAPI会生成OpenAPI 3.0.x兼容的结构：

@router.get("/{itemId}")
async def readItem(
    someParameter: Annotated[Optional[list[str]],
                            Query(
                                title="...",
                                description="...",
                                min_length=3, 
                                max_length=50,
                                nullable=True  # 添加该参数
                            )] = None
):
    # 业务逻辑处理

生成的规范片段会变为：

"name": "someParameter",
"in": "query",
"required": false,
"schema": {
  "type": "array",
  "items": {
    "type": "string"
  },
  "minItems": 3,
  "maxItems": 50,
  "nullable": true
}

模型字段场景 #

用Annotated结合Field，保留Optional类型并添加nullable=True：

from pydantic import BaseModel, Field
from typing import Optional, Annotated

class SomeModel(BaseModel):
    someField: Annotated[Optional[str], Field(nullable=True)] = None

代码中依然保留Optional[str]的类型提示，生成的OpenAPI规范会包含nullable: true，而非anyOf加null类型的结构。

2. 全局处理：批量修改OpenAPI Schema #

如果项目中有大量Optional类型需要处理，手动逐个修改太繁琐，可以自定义OpenAPI生成逻辑，自动将所有包含type: null的anyOf结构替换为nullable: true：

from fastapi.openapi.utils import get_openapi

def customOpenAPI():
    openapiSchema = get_openapi(
        title=app.title,
        openapi_version="3.0.1",
        version=app.version,
        summary=app.summary,
        description=app.description,
        routes=app.routes
    )

    # 遍历所有路径和操作，处理schema结构
    for path in openapiSchema.get("paths", {}).values():
        for operation in path.values():
            # 处理查询参数
            for param in operation.get("parameters", []):
                fix_anyof_null_schema(param.get("schema", {}))
            # 处理请求体
            for content in operation.get("requestBody", {}).get("content", {}).values():
                fix_anyof_null_schema(content.get("schema", {}))
            # 处理响应体
            for resp in operation.get("responses", {}).values():
                for content in resp.get("content", {}).values():
                    fix_anyof_null_schema(content.get("schema", {}))

    app.openapi_schema = openapiSchema
    return app.openapi_schema

def fix_anyof_null_schema(schema):
    """递归处理嵌套的schema，替换anyOf+null结构为nullable"""
    if "anyOf" in schema:
        anyOf_entries = schema["anyOf"]
        has_null = any(entry.get("type") == "null" for entry in anyOf_entries)
        valid_types = [entry for entry in anyOf_entries if entry.get("type") != "null"]
        if has_null and len(valid_types) == 1:
            # 替换为带nullable的单一类型
            schema.clear()
            schema.update(valid_types[0])
            schema["nullable"] = True
    # 处理嵌套属性
    if "properties" in schema:
        for prop in schema["properties"].values():
            fix_anyof_null_schema(prop)
    # 处理数组项
    if "items" in schema:
        fix_anyof_null_schema(schema["items"])

app.openapi = customOpenAPI

这个全局处理函数会自动遍历整个OpenAPI Schema，批量转换不符合3.0.x规范的结构，无需修改业务代码中的Optional类型提示。

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