FastAPI Path参数示例在OpenAPI中位置错误问题求助

问题场景 #

原本计划使用 FastAPI 0.109.2 和 Pydantic 2.7.0 开发接口，编写的接口代码如下：

def get_assessment(
    gr_id: str = Path(description="the id of the global ready assessment", examples={"gr0": {"value": "GR0"}, "gr1": {"value": "GR1"}}), settings: Settings = Depends(get_settings)
) -> Assessment:
    return assessment_service.get_assessement_by_id(gr_id)

生成的OpenAPI YAML里，examples属性被错误嵌套在schema节点内部，而我们需要它和schema同级，期望的正确结构如下：

parameters:
  - name: gr_id
    in: path
    required: true
    schema:
      type: string
      title: Gr Id
    examples:
      gr0:
        value: GR0
      gr1:
        value: GR1
    description: the id of the global ready assessment

无效尝试 #

使用openapi_examples参数仅修改了属性名称，并未修正examples在OpenAPI结构中的位置问题。

最终解决方案 #

排查后发现实际运行环境使用的是 FastAPI 0.100.1，并非计划的0.109.2。执行以下命令升级到FastAPI 0.109.3后，OpenAPI文档生成恢复正常：

poetry update

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