FastAPI-SwaggerUI中如何定义名称带连字符的响应字段并保留类型标注

通过Pydantic字段别名+FastAPI序列化配置即可实现需求，既不用定义不符合Python命名规范的属性，也能保留Swagger文档的完整类型标注。

完整示例代码如下：

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Response(BaseModel):
    # 用Python合法的下划线命名做字段名，alias参数指定返回的JSON键名（支持连字符）
    var_name1: str = Field(..., alias="var-name1")
    
    # Pydantic v2 配置：允许直接用字段名赋值，无需使用别名赋值
    model_config = {
        "populate_by_name": True,
    }

    # 若使用Pydantic v1，配置写法如下
    # class Config:
    #     allow_population_by_field_name = True


@app.put("/", response_model=Response, response_model_by_alias=True)
def simple_server(a: str):
    # 代码侧仍使用下划线命名赋值即可
    response = Response(var_name1=a)
    return response

关键配置说明 #

• 字段的alias参数可以自定义序列化/反序列化时使用的键名，支持连字符、空格等Python变量名不允许的字符
• 路由参数response_model_by_alias=True指定FastAPI序列化响应时，优先使用字段的别名作为JSON键
• 全局生效配置：如果需要所有接口都默认用别名序列化，可以在创建FastAPI实例时添加参数default_response_model_by_alias=True
• Swagger UI会自动读取别名配置，自动展示带连字符的字段名及对应类型标注，无需额外适配

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