FastAPI 与 Pydantic 版本兼容问题导致 `/docs` 报错 500 的解决方案

FastAPI 与 Pydantic 版本兼容问题导致 /docs 报错 500 的解决方案

在使用 FastAPI 开发接口时，遇到访问自动生成的 API 文档（/docs）时报错：

Fetch error
Internal Server Error /openapi.json

或日志中出现类似的：

ERROR:    Exception in ASGI application
Traceback (most recent call last):
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\uvicorn\protocols\http\httptools_impl.py", line 409, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\uvicorn\middleware\proxy_headers.py", line 60, in __call__
    return await self.app(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\fastapi\applications.py", line 1054, in __call__
    await super().__call__(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\applications.py", line 112, in __call__
    await self.middleware_stack(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\middleware\errors.py", line 187, in __call__
    raise exc
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\middleware\errors.py", line 165, in __call__
    await self.app(scope, receive, _send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\middleware\exceptions.py", line 62, in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\routing.py", line 714, in __call__
    await self.middleware_stack(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\routing.py", line 734, in app
    await route.handle(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\routing.py", line 288, in handle
    await self.app(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\routing.py", line 76, in app
    await wrap_app_handling_exceptions(app, request)(scope, receive, send)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\starlette\routing.py", line 73, in app
    response = await f(request)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\fastapi\applications.py", line 1009, in openapi
    return JSONResponse(self.openapi())
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\fastapi\applications.py", line 981, in openapi
    self.openapi_schema = get_openapi(
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\fastapi\openapi\utils.py", line 513, in get_openapi
    schema_generator = GenerateJsonSchema(ref_template=REF_TEMPLATE)
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\pydantic\json_schema.py", line 278, in __init__
    self._schema_type_to_method = self.build_schema_type_to_method()
  File "D:\software\miniconda3\envs\pyfastapi\lib\site-packages\pydantic\json_schema.py", line 317, in build_schema_type_to_method
    method_name = f'{key.replace("-", "_")}_schema'
  File "D:\software\miniconda3\envs\pyfastapi\lib\typing.py", line 647, in __getattr__
    return getattr(self.__origin__, attr)
AttributeError: '_SpecialForm' object has no attribute 'replace'

这是因为 FastAPI 与 Pydantic 版本不兼容引起的。本文将详细介绍问题成因及解决方法。

---

问题背景

• FastAPI 是基于 Pydantic 进行数据校验与模型定义的框架。
• Pydantic 2.x 对类型系统和 JSON Schema 生成进行了重大升级。
• FastAPI 0.115.13 是当前最新稳定版本，官方已支持 Pydantic 2.x，但早期 FastAPI 版本对部分 Pydantic 2.x 版本兼容不完善。

---

错误原因

• 当 Pydantic 版本过高（如 2.11.7）而 FastAPI 版本较旧时，FastAPI 内部调用 Pydantic 的 JSON Schema 生成方法可能失败。
• 报错日志通常包含：

AttributeError: '\_SpecialForm' object has no attribute 'replace'

这说明 FastAPI 期望 Pydantic 返回的类型信息格式与实际不符，导致 OpenAPI Schema 生成失败。

---

解决方案

降级 Pydantic(亲测有效)

将 Pydantic 版本降到与 FastAPI 兼容的稳定版本，例如：

pip install pydantic==2.10.6

该版本在实测中与 FastAPI 0.115.13 兼容良好，解决了 /docs 报错问题。

---

总结

访问 FastAPI 自动生成文档 /docs 报错，绝大多数是 FastAPI 与 Pydantic 版本兼容问题导致的。调整 Pydantic 版本，降级到 2.10.6，配合 FastAPI 0.115.13 使用，基本能解决此问题。

---