FastAPI接口版本控制：如何标记Header中1.1版本为废弃且保留原值

你可以通过给枚举成员添加废弃元数据+返回警告响应头的方式优雅实现需求，既让Swagger UI正确显示废弃标记，又保证请求时只需传入原始版本号1.1。

1. 定义带废弃标记的版本枚举 #

保持枚举成员的实际值为1.1，利用Pydantic的Field为该成员添加deprecated=True标记和描述，FastAPI会自动把这些元数据同步到OpenAPI文档，Swagger UI会识别并显示该版本为废弃状态。

from enum import Enum
from pydantic import Field
from fastapi import FastAPI, Header

app = FastAPI()

class VersionNumber(str, Enum):
    _1_1 = Field("1.1", deprecated=True, description="版本1.1已废弃，请升级至2.0")
    _2_0 = Field("2.0", description="当前最新稳定版本")

2. 处理废弃版本的请求 #

在接口函数中，针对1.1版本的请求，返回符合HTTP规范的Warning响应头，明确告知用户版本已废弃，同时正常返回业务数据，不影响现有依赖该版本的服务。

@app.get("/api/data")
async def fetch_data(accept_version: VersionNumber = Header(..., alias="Accept-Version")):
    response_headers = {}
    if accept_version == VersionNumber._1_1:
        # 追加警告响应头
        response_headers["Warning"] = '299 - "Version 1.1 is deprecated, please upgrade to v2.0"'
        return {"data": "来自废弃版本1.1的内容"}, response_headers
    return {"data": "来自最新版本2.0的内容"}

实际效果 #

• Swagger UI中，Accept-Version下拉选项里的1.1会被标记为废弃（灰色显示+删除线），鼠标悬停可查看预设的废弃提示。
• 请求时只需传入Accept-Version: 1.1即可触发废弃版本逻辑，无需额外后缀。
• 废弃版本的请求会收到Warning响应头，前端或客户端能感知到版本废弃信息。

兼容Pydantic v1的方案 #

如果项目仍在使用Pydantic v1，可通过自定义OpenAPI文档的方式标记枚举选项为废弃：

from enum import Enum
from fastapi import FastAPI, Header
from fastapi.openapi.utils import get_openapi

app = FastAPI()

class VersionNumber(str, Enum):
    _1_1 = "1.1"
    _2_0 = "2.0"

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="你的API名称",
        version="2.0",
        routes=app.routes,
    )
    # 定位Accept-Version的枚举Schema，添加废弃标记
    for schema in openapi_schema["components"]["schemas"].values():
        if schema.get("enum") and "1.1" in schema["enum"]:
            # 添加枚举描述
            schema["enumDescriptions"] = [
                "版本1.1已废弃，请升级至2.0" if v == "1.1" else "当前最新稳定版本"
                for v in schema["enum"]
            ]
            # 标记废弃枚举值
            schema["deprecatedEnums"] = ["1.1"]
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

@app.get("/api/data")
async def fetch_data(accept_version: VersionNumber = Header(..., alias="Accept-Version")):
    response_headers = {}
    if accept_version == VersionNumber._1_1:
        response_headers["Warning"] = '299 - "Version 1.1 is deprecated, please upgrade to v2.0"'
        return {"data": "来自废弃版本1.1的内容"}, response_headers
    return {"data": "来自最新版本2.0的内容"}

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