路径参数¶

你可以使用与 Python 格式化字符串相同的语法来声明路径“参数”或“变量”：

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id):
    return {"item_id": item_id}

路径参数 item_id 的值将作为参数 item_id 传递给您的函数。

因此，如果你运行此示例并访问 http://127.0.0.1:8000/items/foo，你将看到响应：

{"item_id":"foo"}

带类型的路径参数¶

你可以使用标准的 Python 类型注解在函数中声明路径参数的类型：

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

在这种情况下，item_id 被声明为 int 类型。

Check

这将为你的函数内部提供编辑器支持，包括错误检查、自动完成等。

数据转换¶

如果你运行此示例并在浏览器中打开 http://127.0.0.1:8000/items/3，你将看到响应：

{"item_id":3}

Check

请注意，你的函数接收（并返回）的值是 3，是一个 Python int 类型，而不是字符串 "3"。

因此，通过该类型声明，FastAPI 为你提供了自动的请求 “解析”。

数据验证¶

但是如果你在浏览器中访问 http://127.0.0.1:8000/items/foo，你将看到一个清晰的 HTTP 错误：

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": [
        "path",
        "item_id"
      ],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

因为路径参数 item_id 的值为 "foo"，这不是一个 int。

如果你提供的是 float 而不是 int，也会出现同样的错误，例如：http://127.0.0.1:8000/items/4.2

Check

因此，通过相同的 Python 类型声明，FastAPI 为你提供了数据验证。

请注意，错误还清楚地指出了验证失败的具体位置。

这在开发和调试与 API 交互的代码时非常有帮助。

文档¶

当你在浏览器中打开 http://127.0.0.1:8000/docs 时，你会看到自动生成的、交互式的 API 文档，如下所示：

Check

同样，仅通过相同的 Python 类型声明，FastAPI 就为你提供了自动的、交互式的文档（集成了 Swagger UI）。

请注意，路径参数被声明为整数。

基于标准的好处，替代文档¶

并且由于生成的模式来自 OpenAPI 标准，因此有许多兼容的工具。

因此，FastAPI 本身提供了一个替代的 API 文档（使用 ReDoc），你可以通过 http://127.0.0.1:8000/redoc 访问：

同样地，有许多兼容的工具。包括用于多种语言的代码生成工具。

Pydantic¶

所有的数据验证都由 Pydantic 在底层执行，因此你可以获得它的所有好处。并且你知道它是可靠的。

你可以对 str、float、bool 和许多其他复杂数据类型使用相同的类型声明。

本教程的后续章节将探讨其中的几种类型。

顺序很重要¶

在创建路径操作时，你可能会遇到具有固定路径的情况。

例如 /users/me，假设它是用来获取当前用户的数据。

然后你还可以有一个路径 /users/{user_id}，通过用户 ID 获取特定用户的数据。

由于路径操作是按顺序评估的，你需要确保 /users/me 的路径声明在 /users/{user_id} 之前：

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

否则，/users/{user_id} 的路径也会匹配 /users/me，“认为”它接收到了一个值为 "me" 的参数 user_id。

类似地，你不能重定义一个路径操作：

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


@app.get("/users")
async def read_users():
    return ["Rick", "Morty"]


@app.get("/users")
async def read_users2():
    return ["Bean", "Elfo"]

由于路径首先匹配，第一个操作将始终被使用。

预定义值¶

如果你有一个接收路径参数的路径操作，但你希望路径参数的有效值是预定义的，你可以使用标准的 Python Enum。

创建一个 `Enum` 类¶

导入 Enum 并创建一个继承自 str 和 Enum 的子类。

通过继承 str，API 文档将能够知道值必须是 string 类型，并能够正确渲染。

然后创建具有固定值的类属性，这些将是可用的有效值：

Python 3.8+

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Info

枚举（enums）自 Python 3.4 版本起可用。

Tip

如果你想知道，“AlexNet”、“ResNet”和“LeNet”只是机器学习模型的名称。

声明一个路径参数¶

然后使用你创建的枚举类（ModelName）进行类型注解，创建一个路径参数：

Python 3.8+

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

查看文档¶

由于路径参数的可用值是预定义的，交互式文档可以很好地显示它们：

使用 Python 枚举¶

路径参数的值将是一个枚举成员。

比较枚举成员¶

你可以将其与你创建的枚举 ModelName 中的枚举成员进行比较：

Python 3.8+

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

获取枚举值¶

你可以使用 model_name.value 获取实际值（在这种情况下是 str），或者通常使用 your_enum_member.value：

Python 3.8+

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

Tip

你也可以通过 ModelName.lenet.value 访问值 "lenet"。

返回枚举成员¶

你可以从路径操作返回枚举成员，甚至可以嵌套在 JSON 主体中（例如 dict）。

在将它们返回给客户端之前，它们将被转换为相应的值（在这种情况下是字符串）：

Python 3.8+

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

在你的客户端中，你将收到如下的 JSON 响应：

{
  "model_name": "alexnet",
  "message": "Deep Learning FTW!"
}

包含路径的路径参数¶

假设你有一个路径操作，路径为 /files/{file_path}。

但你需要 file_path 本身包含一个路径，例如 home/johndoe/myfile.txt。

因此，该文件的 URL 将类似于：/files/home/johndoe/myfile.txt。

OpenAPI 支持¶

OpenAPI 不支持声明一个路径参数包含内部路径的方式，因为这可能导致难以测试和定义的场景。

尽管如此，你仍然可以在 FastAPI 中实现这一点，使用 Starlette 的一个内部工具。

并且文档仍然有效，尽管不会添加任何说明参数应包含路径的文档。

路径转换器¶

使用直接从 Starlette 提供的选项，你可以声明一个包含路径的路径参数，使用如下的 URL：

/files/{file_path:path}

在这种情况下，参数名是 file_path，最后一部分 :path 告诉它该参数应匹配任何路径。

因此，你可以这样使用它：

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

Tip

你可能需要参数包含一个前导斜杠（/），如 /home/johndoe/myfile.txt。

在这种情况下，URL 将是：/files//home/johndoe/myfile.txt，在 files 和 home 之间有一个双斜杠（//）。

回顾¶

使用 FastAPI，通过简短、直观且标准的 Python 类型声明，你可以获得：

编辑器支持：错误检查、自动完成等。
数据“解析”
数据验证
API 注解和自动文档

并且你只需要声明一次。

这可能是 FastAPI 与其他框架相比的主要可见优势（除了原始性能之外）。

路径参数¶

带类型的路径参数¶

数据 转换¶

数据验证¶

文档¶

基于标准的好处，替代文档¶

Pydantic¶

顺序很重要¶

预定义值¶

创建一个 Enum 类¶

声明一个路径参数¶

查看文档¶

使用 Python 枚举¶

比较枚举成员¶

获取枚举值¶

返回枚举成员¶

包含路径的路径参数¶

OpenAPI 支持¶

路径转换器¶

回顾¶

数据转换¶

创建一个 `Enum` 类¶