FastAPI自学教程（89） - 输入输出分离的OpenAPI架构

1.基础用法

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None  # 带默认值的可选字段

app = FastAPI()

@app.post("/items/")
def create_item(item: Item):  # 输入模型
    return item  # 输出模型

• Pydantic v2会根据字段默认值自动生成不同的OpenAPI架构：
  • 输入模型：description字段非必填（无默认值时必填）
  • 输出模型：description字段必填（始终包含默认值）
• 文档显示差异：

    graph TD
      A[客户端请求] --> B{字段检查}
      B -->|输入模型| C[description可选]
      B -->|输出模型| D[description必填]
      C --> E[允许空值]
      D --> F[值可为null]

2.核心配置

2.1 禁用架构分离

app = FastAPI(separate_input_output_schemas=False)  # 关闭分离模式

• 适用场景：需要保持客户端SDK兼容性时使用
• 效果：输入输出使用相同JSON Schema，忽略默认值差异

2.2 文档验证方法

• 输入端点文档：description字段无红色星号（非必填）
• 输出端点文档：description显示红色星号（必填）
• OpenAPI规范中生成两个Schema：
  • Item-Input：包含可选字段定义
  • Item-Output：包含必填字段定义

3.生产环境建议

1. 客户端兼容：

   • 旧版自动生成客户端可能无法处理多个Schema
   • 迁移期间建议暂时禁用分离：separate_input_output_schemas=False

2. 版本控制：

   class Settings(BaseSettings):
       API_VERSION: str = "2.0"
       separate_schemas: bool = API_VERSION >= "2.0"

   根据API版本动态启用分离特性

3. 安全注意：

   • 文档分离不是安全措施，仍需实施JWT/OAuth2等认证
   • 敏感字段（如密码）应始终使用独立输入模型

完整实现参考：
FastAPI官方文档 - 分离OpenAPI架构
测试命令示例：

# 启用分离模式（默认）
uvicorn main:app

# 禁用分离模式
uvicorn main:app --separate-input-output-schemas false