现在访问%20http://127.0.0.1:8000/docs。

你会看到自动生成的交互式%20API%20文档（由%20Swagger%20UI生成）：

可选的 API 文档

访问 http://127.0.0.1:8000/redoc。

你会看到另一个自动生成的文档（由 ReDoc 生成）：

示例升级

现在修改 main.py 文件来从 PUT 请求中接收请求体。

我们借助 Pydantic 来使用标准的 Python 类型声明请求体。

```Python hl_lines=”4 9-12 25-27” from typing import Union

from fastapi import FastAPI from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel): name: str price: float is_offer: Union[bool, None] = None

@app.get(“/“) def read_root(): return {“Hello”: “World”}

@app.get(“/items/{item_id}”) def read_item(item_id: int, q: Union[str, None] = None): return {“item_id”: item_id, “q”: q}

@app.put(“/items/{item_id}”) def update_item(item_id: int, item: Item): return {“item_name”: item.name, “item_id”: item_id}

服务器将会自动重载（因为在上面的步骤中你向 `uvicorn` 命令添加了 `--reload` 选项）。
### 交互式 API 文档升级
访问 <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>。
* 交互式 API 文档将会自动更新，并加入新的请求体：
![Swagger UI](/uploads/projects/fastapi/202406/17d77d36fda52de1.png)
* 点击「Try it out」按钮，之后你可以填写参数并直接调用 API：
![Swagger UI interaction](/uploads/projects/fastapi/202406/17d77d3b2fb63dec.png)
* 然后点击「Execute」按钮，用户界面将会和 API 进行通信，发送参数，获取结果并在屏幕上展示：
![Swagger UI interaction](/uploads/projects/fastapi/202406/17d77d3f16e5604c.png)
### 可选文档升级
访问 <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>。
* 可选文档同样会体现新加入的请求参数和请求体：
![ReDoc](/uploads/projects/fastapi/202406/17d77d4245ce445d.png)
### 总结
总的来说，你就像声明函数的参数类型一样只声明了**一次**请求参数、请求体等的类型。
你使用了标准的现代 Python 类型来完成声明。
你不需要去学习新的语法、了解特定库的方法或类，等等。
只需要使用标准的 **Python 及更高版本**。
举个例子，比如声明 `int` 类型：
```Python
item_id: int

或者一个更复杂的 Item 模型：

item: Item

……在进行一次声明之后，你将获得：

• 编辑器支持，包括：
  • 自动补全
  • 类型检查
• 数据校验：
  • 在校验失败时自动生成清晰的错误信息
  • 对多层嵌套的 JSON 对象依然执行校验
• 转换 来自网络请求的输入数据为 Python 数据类型。包括以下数据：
  • JSON
  • 路径参数
  • 查询参数
  • Cookies
  • 请求头
  • 表单
  • 文件
• 转换 输出的数据：转换 Python 数据类型为供网络传输的 JSON 数据：
  • 转换 Python 基础类型 （str、 int、 float、 bool、 list 等）
  • datetime 对象
  • UUID 对象
  • 数据库模型
  • ……以及更多其他类型
• 自动生成的交互式 API 文档，包括两种可选的用户界面：
  • Swagger UI
  • ReDoc

回到前面的代码示例，FastAPI 将会：

• 校验 GET 和 PUT 请求的路径中是否含有 item_id。
• 校验 GET 和 PUT 请求中的 item_id 是否为 int 类型。
  • 如果不是，客户端将会收到清晰有用的错误信息。
• 检查 GET 请求中是否有命名为 q 的可选查询参数（比如 http://127.0.0.1:8000/items/foo?q=somequery）。
  • 因为 q 被声明为 = None，所以它是可选的。
  • 如果没有 None 它将会是必需的 (如 PUT 例子中的请求体)。
• 对于访问 /items/{item_id} 的 PUT 请求，将请求体读取为 JSON 并：
  • 检查是否有必需属性 name 并且值为 str 类型 。
  • 检查是否有必需属性 price 并且值为 float 类型。
  • 检查是否有可选属性 is_offer， 如果有的话值应该为 bool 类型。
  • 以上过程对于多层嵌套的 JSON 对象同样也会执行
• 自动对 JSON 进行转换或转换成 JSON。
• 通过 OpenAPI 文档来记录所有内容，可被用于：
  • 交互式文档系统
  • 许多编程语言的客户端代码自动生成系统
• 直接提供 2 种交互式文档 web 界面。

虽然我们才刚刚开始，但其实你已经了解了这一切是如何工作的。

尝试更改下面这行代码：

    return {"item_name": item.name, "item_id": item_id}

……从：

        ... "item_name": item.name ...

……改为：

        ... "item_price": item.price ...

……注意观察编辑器是如何自动补全属性并且还知道它们的类型：

教程 - 用户指南 中有包含更多特性的更完整示例。

剧透警告： 教程 - 用户指南中的内容有：

• 对来自不同地方的参数进行声明，如：请求头、cookies、form 表单以及上传的文件。
• 如何设置校验约束如 maximum_length 或者 regex。
• 一个强大并易于使用的 依赖注入 系统。
• 安全性和身份验证，包括通过 JWT 令牌和 HTTP 基本身份认证来支持 OAuth2。
• 更进阶（但同样简单）的技巧来声明 多层嵌套 JSON 模型 （借助 Pydantic）。
• 许多额外功能（归功于 Starlette）比如：
  • WebSockets
  • GraphQL
  • 基于 HTTPX 和 pytest 的极其简单的测试
  • CORS
  • Cookie Sessions
  • ……以及更多

性能

独立机构 TechEmpower 所作的基准测试结果显示，基于 Uvicorn 运行的 FastAPI 程序是 最快的 Python web 框架之一，仅次于 Starlette 和 Uvicorn 本身（FastAPI 内部使用了它们）。(*)

想了解更多，请查阅 基准测试 章节。

可选依赖

用于 Pydantic：

• email_validator - 用于 email 校验。

用于 Starlette：

• httpx - 使用 TestClient 时安装。
• jinja2 - 使用默认模板配置时安装。
• python-multipart - 需要通过 request.form() 对表单进行「解析」时安装。
• itsdangerous - 需要 SessionMiddleware 支持时安装。
• pyyaml - 使用 Starlette 提供的 SchemaGenerator 时安装（有 FastAPI 你可能并不需要它）。
• graphene - 需要 GraphQLApp 支持时安装。

用于 FastAPI / Starlette：

• uvicorn - 用于加载和运行你的应用程序的服务器。
• orjson - 使用 ORJSONResponse 时安装。
• ujson - 使用 UJSONResponse 时安装。

你可以通过 pip install "fastapi[all]" 命令来安装以上所有依赖。

许可协议

该项目遵循 MIT 许可协议。