FastAPI.Path 中大于 (gt) 和小于 (lt) 的参数在 Swagger UI 中不起作用

Question

使用的版本

• 蟒蛇 3.9.9
• FastAPI 0.95.1
• uvicorn 0.22.0
• 火狐 102.8.0

在这个例子中，路径参数

item_id

设置了有效范围> 100（

gt=100

）和< 1000 (

lt=1000

）。 但是，它在 Swagger UI 中无法识别。

ge

和

le

工作正常。

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get", gt=100, lt=1000)],
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

使用

gt

和

lt

，约束既不会显示在 UI 中也不会强制执行。

使用

ge

和

le

，约束都显示在 UI 中并强制执行。

Answer 1

这似乎是 auto-generated OpenAPI schema 的一个问题，Swagger UI 使用它来提供 interactive API documentation。您可以直接在以下位置查看架构：http://127.0.0.1:8000/openapi.json。鉴于您提供的示例，对于

item_id: int = Path(title="The ID of the item to get", gt=100, lt=1000)

参数，您将看到：

{...,
  "schema": {
    "title": "The ID of the item to get",
    "exclusiveMaximum": 1000,
    "exclusiveMinimum": 0,
    "type": "integer"
  },
  "name": "item_id",
  "in": "path"
}, ...

但是，如 Swagger 文档 中所述，在使用

gt

和

lt

的情况下（意味着应排除

maximum

和

minimum

值），OpenAPI shcema 应该如下所示：

{...,
  "schema": {
    "title": "The ID of the item to get",
    "maximum": 1000,
    "exclusiveMaximum": true,
    "minimum": 0,
    "exclusiveMinimum": true,
    "type": "integer"
  },
  "name": "item_id",
  "in": "path"
}...

因此，

exclusiveMaximum

和

exclusiveMinimum

属性应该采用 boolean 值，而不是实际的数值本身。可以加载他们自己修改过的 OpenAPI shcema，如here 和 here 所示，但即使 Swagger 会显示

minimum

和

maximum

值（如果使用类似于上面演示的修改过的模式），它也会仍然没有让用户清楚

minimum

和

maximum

值被排除在外（例如，大于/小于符号）。此外，例如，如果用户将

1000

传递给

item_id

，验证将不会在前端进行并在 Swagger UI 中显示验证错误消息（例如，

Value must be less than 1000

）——因为它会在使用时发生

ge

和

le

——而是在后端，它将以适当的验证错误消息作为响应。因此，生成的 OpenAPI shcema 和 Swagger UI 也可能存在问题。