如何在FastAPI Swagger UI中隐藏字段但仍支持手动传入值？

DevOps 小满

2026-8-21

在FastAPI Swagger UI中隐藏字段并保留手动传入能力的解决方案

问题原因

你之前的方案中，下划线开头的_difficulty被Pydantic默认视为私有字段，不会参与请求数据的解析流程，所以即使设置了alias='difficulty'，传入的difficulty值也无法被映射到_difficulty，只会保留默认值'low'。

解决方案

以下是两种可行的实现方式：

方案一：直接设置字段不纳入OpenAPI Schema

不需要使用下划线命名，通过Field的include_in_schema=False参数让字段在Swagger UI中隐藏，同时保留正常的字段解析能力：

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Subject(BaseModel):
    score: int
    # 设置include_in_schema=False，Swagger UI中不会显示该字段，但可接收传入值
    difficulty: str = Field('low', include_in_schema=False)

@app.post("/submit")
async def submit(subject: Subject):
    return {
        "score": subject.score,
        "difficulty": subject.difficulty  # 可正常获取传入的difficulty值
    }

方案二：保留下划线字段并关闭私有属性限制

如果坚持要使用下划线命名字段，需要在模型配置中关闭underscore_attrs_are_private的默认限制，同时设置include_in_schema=False隐藏Swagger显示：

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Subject(BaseModel):
    score: int
    _difficulty: str = Field('low', alias='difficulty', include_in_schema=False)
    
    # 关闭下划线字段的私有属性限制，让Pydantic解析该字段
    model_config = {
        "underscore_attrs_are_private": False
    }

@app.post("/submit")
async def submit(subject: Subject):
    return {
        "score": subject.score,
        "difficulty": subject._difficulty  # 可正确获取别名传入的值
    }