diff --git a/docs/zh/docs/advanced/additional-responses.md b/docs/zh/docs/advanced/additional-responses.md
index 365ba3db4f..842d49b4ca 100644
--- a/docs/zh/docs/advanced/additional-responses.md
+++ b/docs/zh/docs/advanced/additional-responses.md
@@ -34,7 +34,7 @@
///
-/// info | 信息
+/// note | 注意
`model` 键不是 OpenAPI 的一部分。
@@ -183,7 +183,7 @@
///
-/// info | 信息
+/// note | 注意
除非你在 `responses` 参数中明确指定不同的媒体类型，否则 FastAPI 会假设响应与主响应类具有相同的媒体类型（默认是 `application/json`）。
diff --git a/docs/zh/docs/advanced/advanced-dependencies.md b/docs/zh/docs/advanced/advanced-dependencies.md
index edaf964c93..da299a6bfc 100644
--- a/docs/zh/docs/advanced/advanced-dependencies.md
+++ b/docs/zh/docs/advanced/advanced-dependencies.md
@@ -98,7 +98,7 @@ checker(q="somequery")
在 0.118.0 中，这一行为被回退为：让 `yield` 之后的退出代码在响应发送之后再执行。
-/// info | 信息
+/// note | 注意
如你在下文所见，这与 0.106.0 之前的行为非常相似，但对若干边界情况做了改进和修复。
diff --git a/docs/zh/docs/advanced/custom-response.md b/docs/zh/docs/advanced/custom-response.md
index ce595572dd..053fa34c7d 100644
--- a/docs/zh/docs/advanced/custom-response.md
+++ b/docs/zh/docs/advanced/custom-response.md
@@ -41,7 +41,7 @@
{* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *}
-/// info | 信息
+/// note | 注意
参数 `response_class` 也会用来定义响应的「媒体类型」。
@@ -65,7 +65,7 @@
///
-/// info | 信息
+/// note | 注意
当然，实际的 `Content-Type` 头、状态码等等，将来自于你返回的 `Response` 对象。
diff --git a/docs/zh/docs/advanced/dataclasses.md b/docs/zh/docs/advanced/dataclasses.md
index 42b4e4cc4d..a46615286c 100644
--- a/docs/zh/docs/advanced/dataclasses.md
+++ b/docs/zh/docs/advanced/dataclasses.md
@@ -18,7 +18,7 @@ FastAPI 基于 **Pydantic** 构建，我已经向你展示过如何使用 Pydant
这与使用 Pydantic 模型时的工作方式相同。而且底层实际上也是借助 Pydantic 实现的。
-/// info | 信息
+/// note | 注意
请注意，数据类不能完成 Pydantic 模型能做的所有事情。
diff --git a/docs/zh/docs/advanced/events.md b/docs/zh/docs/advanced/events.md
index 0b647a4388..e1bb2ed60b 100644
--- a/docs/zh/docs/advanced/events.md
+++ b/docs/zh/docs/advanced/events.md
@@ -120,7 +120,7 @@ async with lifespan(app):
此处，`shutdown` 事件处理器函数会向文件 `log.txt` 写入一行文本 `"Application shutdown"`。
-/// info | 信息
+/// note | 注意
在 `open()` 函数中，`mode="a"` 指的是“追加”。因此这行文本会添加在文件已有内容之后，不会覆盖之前的内容。
@@ -152,7 +152,7 @@ async with lifespan(app):
在底层，这部分是 ASGI 技术规范中的 [Lifespan 协议](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)的一部分，定义了称为 `startup` 和 `shutdown` 的事件。
-/// info | 信息
+/// note | 注意
你可以在 [Starlette 的 Lifespan 文档](https://www.starlette.dev/lifespan/) 中阅读更多关于 `lifespan` 处理器的内容。
diff --git a/docs/zh/docs/advanced/generate-clients.md b/docs/zh/docs/advanced/generate-clients.md
index 049241bc90..9feaf6cf56 100644
--- a/docs/zh/docs/advanced/generate-clients.md
+++ b/docs/zh/docs/advanced/generate-clients.md
@@ -31,7 +31,6 @@ FastAPI 会自动生成 **OpenAPI 3.1** 规范，因此你使用的任何工具
例如，你可以尝试：
* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral)
-* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi)
其中一些方案也可能是开源的或提供免费层级，你可以不花钱就先试用。其他商业 SDK 生成器也可在网上找到。🤓
@@ -83,7 +82,7 @@ npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client
///
-你发送的数据如果不符合要求，会在编辑器中显示内联错误：
+你发送的数据会有**内联错误**：
diff --git a/docs/zh/docs/advanced/openapi-callbacks.md b/docs/zh/docs/advanced/openapi-callbacks.md
index 49cef36481..f4f2e7b81d 100644
--- a/docs/zh/docs/advanced/openapi-callbacks.md
+++ b/docs/zh/docs/advanced/openapi-callbacks.md
@@ -173,7 +173,7 @@ JSON 请求体包含如下内容：
/// tip | 提示
-注意，不能把路由本身（`invoices_callback_router`）传递给 `callbacks=`，要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。
+注意，不能把路由本身（`invoices_callback_router`）传递给 `callbacks=`，要传递 `invoices_callback_router.routes` 中的 `.routes` 属性。FastAPI 会使用这些路由来生成回调的 OpenAPI 文档。
///
diff --git a/docs/zh/docs/advanced/openapi-webhooks.md b/docs/zh/docs/advanced/openapi-webhooks.md
index 3d6bcc9bc2..8bec3b6181 100644
--- a/docs/zh/docs/advanced/openapi-webhooks.md
+++ b/docs/zh/docs/advanced/openapi-webhooks.md
@@ -22,7 +22,7 @@
这能让您的用户更轻松地**实现他们的 API** 来接收您的**网络钩子**请求，他们甚至可能能够自动生成一些自己的 API 代码。
-/// info | 信息
+/// note | 注意
网络钩子在 OpenAPI 3.1.0 及以上版本中可用，FastAPI `0.99.0` 及以上版本支持。
@@ -36,7 +36,7 @@
您定义的网络钩子将被包含在 `OpenAPI` 的架构中，并出现在自动生成的**文档 UI** 中。
-/// info | 信息
+/// note | 注意
`app.webhooks` 对象实际上只是一个 `APIRouter` ，与您在使用多个文件来构建应用程序时所使用的类型相同。
diff --git a/docs/zh/docs/advanced/path-operation-advanced-configuration.md b/docs/zh/docs/advanced/path-operation-advanced-configuration.md
index 67f3bd7e9a..a9f2c1e860 100644
--- a/docs/zh/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/zh/docs/advanced/path-operation-advanced-configuration.md
@@ -16,17 +16,11 @@
### 使用 *路径操作函数* 的函数名作为 operationId { #using-the-path-operation-function-name-as-the-operationid }
-如果你想用 API 的函数名作为 `operationId`，你可以遍历所有路径操作，并使用它们的 `APIRoute.name` 重写每个 *路径操作* 的 `operation_id`。
+如果你想用 API 的函数名作为 `operationId`，你可以向 `FastAPI` 传入自定义的 `generate_unique_id_function`。
-你应该在添加了所有 *路径操作* 之后执行此操作。
+该函数会接收每个 `APIRoute`，并返回用于该路径操作的 `operationId`。
-{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *}
-
-/// tip
-
-如果你手动调用 `app.openapi()`，你应该在此之前更新 `operationId`。
-
-///
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2,5:6,9] *}
/// warning
diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md
index 1966221467..f9a865137c 100644
--- a/docs/zh/docs/advanced/response-directly.md
+++ b/docs/zh/docs/advanced/response-directly.md
@@ -5,9 +5,9 @@
如果你声明了 [响应模型](../tutorial/response-model.md)，FastAPI 会使用它通过 Pydantic 将数据序列化为 JSON。
如果你没有声明响应模型，**FastAPI** 会使用在 [JSON 兼容编码器](../tutorial/encoder.md) 中阐述的 `jsonable_encoder`。
-然后，**FastAPI** 会在后台将这些兼容 JSON 的数据（比如字典）放到一个 `JSONResponse` 中，该 `JSONResponse` 会用来发送响应给客户端。
+然后，**FastAPI** 会将其放入一个 `JSONResponse` 中。
-但是你可以在你的 *路径操作* 中直接返回一个 `JSONResponse`。
+你也可以直接创建一个 `JSONResponse` 并返回它。
/// tip | 提示
@@ -17,9 +17,9 @@
## 返回 `Response` { #return-a-response }
-事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。
+你可以返回一个 `Response` 或其任意子类。
-/// info | 信息
+/// note | 注意
`JSONResponse` 本身是一个 `Response` 的子类。
diff --git a/docs/zh/docs/advanced/security/oauth2-scopes.md b/docs/zh/docs/advanced/security/oauth2-scopes.md
index a1ecc641ca..db29e49163 100644
--- a/docs/zh/docs/advanced/security/oauth2-scopes.md
+++ b/docs/zh/docs/advanced/security/oauth2-scopes.md
@@ -46,7 +46,7 @@ OAuth2 规范将“作用域”定义为由空格分隔的字符串列表。
* Facebook / Instagram 使用 `instagram_basic`
* Google 使用 `https://www.googleapis.com/auth/drive`
-/// info | 信息
+/// note | 注意
在 OAuth2 中，“作用域”只是一个声明所需特定权限的字符串。
@@ -126,7 +126,7 @@ OAuth2 规范将“作用域”定义为由空格分隔的字符串列表。
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
-/// info | 技术细节
+/// note | 技术细节
`Security` 实际上是 `Depends` 的子类，它只多了一个我们稍后会看到的参数。
diff --git a/docs/zh/docs/advanced/stream-data.md b/docs/zh/docs/advanced/stream-data.md
index 322561ac11..366ab203be 100644
--- a/docs/zh/docs/advanced/stream-data.md
+++ b/docs/zh/docs/advanced/stream-data.md
@@ -4,7 +4,7 @@
但如果你想流式传输纯二进制数据或字符串，可以按下面的方法操作。
-/// info | 信息
+/// note | 注意
自 FastAPI 0.134.0 起新增。
@@ -90,7 +90,7 @@ FastAPI 会将每个数据块原样交给 `StreamingResponse`，不会尝试将
而且很多情况下，读取它们是一个阻塞操作（可能会阻塞事件循环），因为数据来自磁盘或网络。
-/// info | 信息
+/// note | 注意
上面的示例其实是个例外，因为 `io.BytesIO` 对象已经在内存中，所以读取它不会阻塞。
diff --git a/docs/zh/docs/advanced/strict-content-type.md b/docs/zh/docs/advanced/strict-content-type.md
index 973d1840c0..0cf9242aff 100644
--- a/docs/zh/docs/advanced/strict-content-type.md
+++ b/docs/zh/docs/advanced/strict-content-type.md
@@ -81,7 +81,7 @@ http://localhost:8000/v1/agents/multivac
启用该设置后，缺少 `Content-Type` 头的请求其请求体也会按 JSON 解析，这与旧版本 FastAPI 的行为一致。
-/// info | 信息
+/// note | 注意
此行为和配置在 FastAPI 0.132.0 中新增。
diff --git a/docs/zh/docs/advanced/websockets.md b/docs/zh/docs/advanced/websockets.md
index d90ef87339..7950f90eaa 100644
--- a/docs/zh/docs/advanced/websockets.md
+++ b/docs/zh/docs/advanced/websockets.md
@@ -111,11 +111,11 @@ $ fastapi dev
{* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *}
-/// info
+/// note | 注意
由于这是一个 WebSocket，抛出 `HTTPException` 并不是很合理，而是抛出 `WebSocketException`。
-您可以使用[规范中定义的有效代码](https://tools.ietf.org/html/rfc6455#section-7.4.1)。
+您可以使用[规范中定义的有效关闭代码](https://tools.ietf.org/html/rfc6455#section-7.4.1)。
///
@@ -140,7 +140,7 @@ $ fastapi dev
* "Item ID"，用于路径。
* "Token"，作为查询参数。
-/// tip
+/// tip | 提示
注意，查询参数 `token` 将由依赖项处理。
@@ -168,13 +168,13 @@ $ fastapi dev
Client #1596980209979 left the chat
```
-/// tip
+/// tip | 提示
上面的应用程序是一个最小和简单的示例，用于演示如何处理和向多个 WebSocket 连接广播消息。
但请记住，由于所有内容都在内存中以单个列表的形式处理，因此它只能在进程运行时工作，并且只能使用单个进程。
-如果您需要与 FastAPI 集成更简单但更强大的功能，支持 Redis、PostgreSQL 或其他功能，请查看 [encode/broadcaster](https://github.com/encode/broadcaster)。
+如果您需要与 FastAPI 集成更简单但更健壮的方案，支持 Redis、PostgreSQL 或其他，请查看 [encode/broadcaster](https://github.com/encode/broadcaster)。
///
diff --git a/docs/zh/docs/advanced/wsgi.md b/docs/zh/docs/advanced/wsgi.md
index 038b672f8a..f665c371f4 100644
--- a/docs/zh/docs/advanced/wsgi.md
+++ b/docs/zh/docs/advanced/wsgi.md
@@ -6,7 +6,7 @@
## 使用 `WSGIMiddleware` { #using-wsgimiddleware }
-/// info | 信息
+/// note | 注意
需要安装 `a2wsgi`，例如使用 `pip install a2wsgi`。
diff --git a/docs/zh/docs/deployment/docker.md b/docs/zh/docs/deployment/docker.md
index aa7b60b508..c1b216953e 100644
--- a/docs/zh/docs/deployment/docker.md
+++ b/docs/zh/docs/deployment/docker.md
@@ -132,7 +132,7 @@ Successfully installed fastapi pydantic
-/// info | 信息
+/// note | 注意
还有其他格式和工具可以定义并安装包依赖。
@@ -556,7 +556,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"]
如果你有**多个容器**，可能每个容器运行一个**单独进程**（例如在 **Kubernetes** 集群中），那么你可能希望使用一个**单独的容器**来执行**前置步骤**，在一个容器中运行一个进程，**在**启动那些复制的 worker 容器**之前**完成。
-/// info | 信息
+/// note | 注意
如果你使用 Kubernetes，这通常会是一个 [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)。
diff --git a/docs/zh/docs/deployment/fastapicloud.md b/docs/zh/docs/deployment/fastapicloud.md
index d438709935..9140e30c05 100644
--- a/docs/zh/docs/deployment/fastapicloud.md
+++ b/docs/zh/docs/deployment/fastapicloud.md
@@ -1,26 +1,6 @@
# FastAPI Cloud { #fastapi-cloud }
-你可以用**一条命令**将你的 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)，如果还没有，去加入候补名单吧。🚀
-
-## 登录 { #login }
-
-请确保你已有 **FastAPI Cloud** 账号（我们已从候补名单向你发出邀请 😉）。
-
-然后登录：
-
-
-
-```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud 🚀
-```
-
-
-
-## 部署 { #deploy }
-
-现在用**一条命令**部署你的应用：
+你可以用**一条命令**将你的 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)。🚀
@@ -36,6 +16,8 @@ Deploying to FastAPI Cloud...
+CLI 会自动检测你的 FastAPI 应用并将其部署到云端。如果你尚未登录，浏览器会自动打开以完成认证流程。
+
就这样！现在你可以通过该 URL 访问你的应用。✨
## 关于 FastAPI Cloud { #about-fastapi-cloud }
diff --git a/docs/zh/docs/deployment/manually.md b/docs/zh/docs/deployment/manually.md
index c440aa924b..a395f96da5 100644
--- a/docs/zh/docs/deployment/manually.md
+++ b/docs/zh/docs/deployment/manually.md
@@ -56,7 +56,6 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称
* [Hypercorn](https://hypercorn.readthedocs.io/): 与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。
* [Daphne](https://github.com/django/daphne): 为 Django Channels 构建的 ASGI 服务器。
* [Granian](https://github.com/emmett-framework/granian): 基于 Rust 的 HTTP 服务器，专为 Python 应用设计。
-* [NGINX Unit](https://unit.nginx.org/howto/fastapi/): NGINX Unit 是一个轻量级且灵活的 Web 应用运行时环境。
## 服务器主机和服务器程序 { #server-machine-and-server-program }
diff --git a/docs/zh/docs/deployment/server-workers.md b/docs/zh/docs/deployment/server-workers.md
index add83ac1af..e20d9ef95f 100644
--- a/docs/zh/docs/deployment/server-workers.md
+++ b/docs/zh/docs/deployment/server-workers.md
@@ -17,7 +17,7 @@
在本章节中，我将向您展示如何使用 `fastapi` 命令或直接使用 `uvicorn` 命令以**多工作进程模式**运行 **Uvicorn**。
-/// info | 信息
+/// note | 注意
如果您正在使用容器，例如 Docker 或 Kubernetes，我将在下一章中告诉您更多相关信息：[容器中的 FastAPI - Docker](docker.md)。
diff --git a/docs/zh/docs/how-to/extending-openapi.md b/docs/zh/docs/how-to/extending-openapi.md
index fd39e439fa..9b8d1c07e0 100644
--- a/docs/zh/docs/how-to/extending-openapi.md
+++ b/docs/zh/docs/how-to/extending-openapi.md
@@ -25,9 +25,17 @@
- `openapi_version`：使用的 OpenAPI 规范版本。默认是最新的 `3.1.0`。
- `summary`：API 的简短摘要。
- `description`：API 的描述，可包含 Markdown，并会展示在文档中。
-- `routes`：路由列表，即已注册的每个路径操作。来自 `app.routes`。
+- `routes`：应用的路由，来自 `app.routes`。FastAPI 使用它们来收集已注册的路径操作，包括来自已包含路由器的那些。
-/// info | 信息
+/// tip | 技术细节
+
+`app.routes` 是一个更底层的路由树。它可能包含 FastAPI 在内部用于包含的路由器的候选路由，而不仅仅是最终的 `APIRoute` 对象。
+
+你仍然可以把 `app.routes` 传给 `get_openapi()`。FastAPI 会遍历这棵路由树来收集实际生效的路径操作。
+
+///
+
+/// note | 注意
参数 `summary` 仅在 OpenAPI 3.1.0 及更高版本中可用，FastAPI 0.99.0 及以上版本支持。
@@ -61,7 +69,7 @@
你可以把 `.openapi_schema` 属性当作“缓存”，用来存储已生成的架构。
-这样一来，用户每次打开 API 文档时，应用就不必重新生成架构。
+这样一来，应用每次打开 API 文档时就不必重新生成架构。
它只会生成一次，后续请求都会使用同一份缓存的架构。
diff --git a/docs/zh/docs/how-to/separate-openapi-schemas.md b/docs/zh/docs/how-to/separate-openapi-schemas.md
index c3efe5f1a4..19d372b461 100644
--- a/docs/zh/docs/how-to/separate-openapi-schemas.md
+++ b/docs/zh/docs/how-to/separate-openapi-schemas.md
@@ -85,7 +85,7 @@
这种情况下，你可以在 **FastAPI** 中通过参数 `separate_input_output_schemas=False` 禁用该特性。
-/// info | 信息
+/// note | 注意
对 `separate_input_output_schemas` 的支持是在 FastAPI `0.102.0` 中添加的。🤓
diff --git a/docs/zh/docs/index.md b/docs/zh/docs/index.md
index f89d0a6531..74b799e5c1 100644
--- a/docs/zh/docs/index.md
+++ b/docs/zh/docs/index.md
@@ -492,9 +492,7 @@ item: Item
### 部署你的应用（可选） { #deploy-your-app-optional }
-你可以选择把 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)，如果还没有的话去加入候补名单吧。🚀
-
-如果你已经有 **FastAPI Cloud** 账号（我们从候补名单邀请了你 😉），你可以用一个命令部署你的应用。
+你可以选择用一条命令将 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)。🚀
@@ -510,6 +508,8 @@ Deploying to FastAPI Cloud...
+CLI 会自动检测你的 FastAPI 应用并将其部署到云端。如果你尚未登录，浏览器会打开以完成认证流程。
+
就这样！现在你可以通过该 URL 访问你的应用了。✨
#### 关于 FastAPI Cloud { #about-fastapi-cloud }
diff --git a/docs/zh/docs/tutorial/bigger-applications.md b/docs/zh/docs/tutorial/bigger-applications.md
index cbee84f35a..1be1be6284 100644
--- a/docs/zh/docs/tutorial/bigger-applications.md
+++ b/docs/zh/docs/tutorial/bigger-applications.md
@@ -396,9 +396,9 @@ from .routers.users import router
/// note | 技术细节
-实际上，它将在内部为声明在 `APIRouter` 中的每个*路径操作*创建一个*路径操作*。
+当在主应用中包含路由器时，FastAPI 会保留原始的 `APIRouter` 及其 `APIRoute` 处于活动状态。
-所以，在幕后，它实际上会像所有的东西都是同一个应用程序一样工作。
+这意味着自定义的 `APIRouter` 和 `APIRoute` 子类在被包含之后仍然能够参与工作。
///
@@ -406,7 +406,7 @@ from .routers.users import router
包含路由器时，你不必担心性能问题。
-这将花费几微秒时间，并且只会在启动时发生。
+这被设计为轻量级的，并且避免给每个请求增加开销。
因此，它不会影响性能。⚡
@@ -457,11 +457,11 @@ from .routers.users import router
---
-`APIRouter` 没有被「挂载」，它们与应用程序的其余部分没有隔离。
+`APIRouter` 并不是「挂载」的，它们并没有和应用程序的其余部分隔离。
-这是因为我们想要在 OpenAPI 模式和用户界面中包含它们的*路径操作*。
+这是因为我们希望在 OpenAPI 模式和用户界面中包含它们的*路径操作*。
-由于我们不能仅仅隔离它们并独立于其余部分来「挂载」它们，因此*路径操作*是被「克隆的」（重新创建），而不是直接包含。
+FastAPI 会保留原始的路由器和路径操作处于活动状态，并在处理请求和生成 OpenAPI 时组合路由器的前缀、依赖项、标签、响应以及其他元数据。
///
@@ -532,4 +532,16 @@ $ fastapi dev
router.include_router(other_router)
```
-请确保在你将 `router` 包含到 `FastAPI` 应用程序之前进行此操作，以便 `other_router` 中的*路径操作*也能被包含进来。
+你可以在将 `router` 包含到 `FastAPI` 应用之前或之后执行此操作。FastAPI 仍然会在路由和 OpenAPI 中包含 `other_router` 中的*路径操作*。
+
+同样适用于之后添加到这些路由器的*路径操作*。它们也会通过先前的包含可见。
+
+/// warning | 技术细节
+
+在包含路由器之后，避免直接修改 `router.routes`。FastAPI 将路由器的包含视为「实时」的，因此原始路由器及其路由会继续参与路由和 OpenAPI 生成。
+
+使用文档化的 API（例如路径操作装饰器和 `.include_router()`）来添加路由和路由器。
+
+将 `router.routes` 视为较低层级的路由树，它可以包含路由定义和被包含的路由器；避免把它当作最终路径操作的扁平列表来依赖。
+
+///
diff --git a/docs/zh/docs/tutorial/body-multiple-params.md b/docs/zh/docs/tutorial/body-multiple-params.md
index 39b84904fc..8cb465764f 100644
--- a/docs/zh/docs/tutorial/body-multiple-params.md
+++ b/docs/zh/docs/tutorial/body-multiple-params.md
@@ -108,7 +108,7 @@ q: str | None = None
{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
-/// info | 信息
+/// note | 注意
`Body` 同样具有与 `Query`、`Path` 以及其他后面将看到的类完全相同的额外校验和元数据参数。
@@ -123,7 +123,7 @@ q: str | None = None
但是，如果你希望它期望一个拥有 `item` 键并在值中包含模型内容的 JSON，就像在声明额外的请求体参数时所做的那样，则可以使用一个特殊的 `Body` 参数 `embed`：
```Python
-item: Item = Body(embed=True)
+item: Annotated[Item, Body(embed=True)]
```
比如：
diff --git a/docs/zh/docs/tutorial/body-nested-models.md b/docs/zh/docs/tutorial/body-nested-models.md
index 93a34da553..98e5168aa5 100644
--- a/docs/zh/docs/tutorial/body-nested-models.md
+++ b/docs/zh/docs/tutorial/body-nested-models.md
@@ -135,7 +135,7 @@ Pydantic 模型的每个属性都具有类型。
}
```
-/// info | 信息
+/// note | 注意
请注意 `images` 键现在具有一组 image 对象是如何发生的。
@@ -147,9 +147,9 @@ Pydantic 模型的每个属性都具有类型。
{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
-/// info | 信息
+/// note | 注意
-请注意 `Offer` 拥有一组 `Item` 而反过来 `Item` 又是一个可选的 `Image` 列表是如何发生的。
+请注意 `Offer` 拥有一组 `Item` 而反过来 `Item` 又有一个可选的 `Image` 列表是如何发生的。
///
diff --git a/docs/zh/docs/tutorial/body.md b/docs/zh/docs/tutorial/body.md
index 0a4c9c5e53..ee4124e945 100644
--- a/docs/zh/docs/tutorial/body.md
+++ b/docs/zh/docs/tutorial/body.md
@@ -8,7 +8,7 @@
使用 [Pydantic](https://docs.pydantic.dev/) 模型来声明**请求体**，能充分利用它的功能和优点。
-/// info | 信息
+/// note | 注意
发送数据应使用以下之一：`POST`（最常见）、`PUT`、`DELETE` 或 `PATCH`。
diff --git a/docs/zh/docs/tutorial/cookie-param-models.md b/docs/zh/docs/tutorial/cookie-param-models.md
index 8e094c7d3f..368fe47626 100644
--- a/docs/zh/docs/tutorial/cookie-param-models.md
+++ b/docs/zh/docs/tutorial/cookie-param-models.md
@@ -1,8 +1,8 @@
# Cookie 参数模型 { #cookie-parameter-models }
-如果您有一组相关的 **cookie**，您可以创建一个 **Pydantic 模型**来声明它们。🍪
+如果你有一组相关的 **cookie**，你可以创建一个 **Pydantic 模型**来声明它们。🍪
-这将允许您在**多个地方**能够**重用模型**，并且可以一次性声明所有参数的验证方式和元数据。😎
+这将允许你在**多个地方**能够**重用模型**，并且可以一次性声明所有参数的验证方式和元数据。😎
/// note | 注意
@@ -22,39 +22,39 @@
{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
-**FastAPI** 将从请求中接收到的 **cookie** 中**提取**出**每个字段**的数据，并提供您定义的 Pydantic 模型。
+**FastAPI** 将从请求中接收到的 **cookie** 中**提取**出**每个字段**的数据，并提供你定义的 Pydantic 模型。
## 查看文档 { #check-the-docs }
-您可以在文档 UI 的 `/docs` 中查看定义的 cookie：
+你可以在文档 UI 的 `/docs` 中查看定义的 cookie：
-/// info | 信息
+/// note | 注意
请记住，由于**浏览器**以特殊方式**处理 cookie**，并在后台进行操作，因此它们**不会**轻易允许 **JavaScript** 访问这些 cookie。
-如果您访问 `/docs` 的 **API 文档 UI**，您将能够查看您*路径操作*的 cookie **文档**。
+如果你访问 `/docs` 的 **API 文档 UI**，你将能够查看你*路径操作*的 cookie **文档**。
-但是即使您**填写数据**并点击“执行”，由于文档界面使用 **JavaScript**，cookie 将不会被发送。而您会看到一条**错误**消息，就好像您没有输入任何值一样。
+但是即使你**填写数据**并点击“执行”，由于文档界面使用 **JavaScript**，cookie 将不会被发送。而你会看到一条**错误**消息，就好像你没有输入任何值一样。
///
## 禁止额外的 Cookie { #forbid-extra-cookies }
-在某些特殊使用情况下（可能并不常见），您可能希望**限制**您想要接收的 cookie。
+在某些特殊使用情况下（可能并不常见），你可能希望**限制**你想要接收的 cookie。
-您的 API 现在可以控制自己的 cookie 同意。🤪🍪
+你的 API 现在可以控制自己的 cookie 同意。🤪🍪
-您可以使用 Pydantic 的模型配置来禁止（ `forbid` ）任何额外（ `extra` ）字段：
+你可以使用 Pydantic 的模型配置来禁止（ `forbid` ）任何额外（ `extra` ）字段：
{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *}
如果客户端尝试发送一些**额外的 cookie**，他们将收到**错误**响应。
-可怜的 cookie 通知条，费尽心思为了获得您的同意，却被API 拒绝了。🍪
+可怜的 cookie 通知条，费尽心思为了获得你的同意，却被API 拒绝了。🍪
例如，如果客户端尝试发送一个值为 `good-list-please` 的 `santa_tracker` cookie，客户端将收到一个**错误**响应，告知他们 `santa_tracker` cookie 是不允许的：
@@ -73,4 +73,4 @@
## 总结 { #summary }
-您可以使用 **Pydantic 模型**在 **FastAPI** 中声明 **cookie**。😎
+你可以使用 **Pydantic 模型**在 **FastAPI** 中声明 **cookie**。😎
diff --git a/docs/zh/docs/tutorial/cookie-params.md b/docs/zh/docs/tutorial/cookie-params.md
index ab05cd7d24..97bf00c65b 100644
--- a/docs/zh/docs/tutorial/cookie-params.md
+++ b/docs/zh/docs/tutorial/cookie-params.md
@@ -12,7 +12,7 @@
声明 `Cookie` 参数的方式与声明 `Query` 和 `Path` 参数相同。
-第一个值是默认值，还可以传递所有验证参数或注释参数：
+你可以定义默认值，以及所有额外的验证或注解参数：
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *}
@@ -24,13 +24,13 @@
///
-/// info | 信息
+/// note | 注意
必须使用 `Cookie` 声明 cookie 参数，否则该参数会被解释为查询参数。
///
-/// info | 信息
+/// note | 注意
请注意，由于**浏览器会以特殊方式并在幕后处理 cookies**，它们**不会**轻易允许**JavaScript**访问它们。
diff --git a/docs/zh/docs/tutorial/debugging.md b/docs/zh/docs/tutorial/debugging.md
index 19e6f8a612..4f4503eef3 100644
--- a/docs/zh/docs/tutorial/debugging.md
+++ b/docs/zh/docs/tutorial/debugging.md
@@ -42,12 +42,14 @@ $ python myapp.py
那么文件中由 Python 自动创建的内部变量 `__name__`，会将字符串 `"__main__"` 作为值。
-所以，下面这部分代码才会运行：
+所以，这一段：
```Python
uvicorn.run(app, host="0.0.0.0", port=8000)
```
+会运行。
+
---
如果你是导入这个模块（文件）就不会这样。
@@ -62,13 +64,15 @@ from myapp import app
在这种情况下，`myapp.py` 内部的自动变量不会有值为 `"__main__"` 的变量 `__name__`。
-所以，下面这一行不会被执行：
+所以，这一行：
```Python
uvicorn.run(app, host="0.0.0.0", port=8000)
```
-/// info | 信息
+不会被执行。
+
+/// note | 注意
更多信息请检查 [Python 官方文档](https://docs.python.org/3/library/__main__.html).
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index a3b2e6a41e..afd3dc9823 100644
--- a/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -28,7 +28,7 @@
///
-/// info | 信息
+/// note | 注意
本例中，使用的是自定义响应头 `X-Key` 和 `X-Token`。
diff --git a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
index a365bccf04..5beda57099 100644
--- a/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -170,7 +170,7 @@ participant tasks as Background tasks
end
```
-/// info | 信息
+/// note | 注意
只会向客户端发送**一次响应**。它可能是某个错误响应，或者是来自 *路径操作* 的响应。
diff --git a/docs/zh/docs/tutorial/dependencies/index.md b/docs/zh/docs/tutorial/dependencies/index.md
index 939470f409..08a04ad88e 100644
--- a/docs/zh/docs/tutorial/dependencies/index.md
+++ b/docs/zh/docs/tutorial/dependencies/index.md
@@ -51,7 +51,7 @@
然后它只需返回一个包含这些值的 `dict`。
-/// info | 信息
+/// note | 注意
FastAPI 在 0.95.0 版本中新增了对 `Annotated` 的支持（并开始推荐使用）。
@@ -106,7 +106,7 @@ common_parameters --> read_users
这样，你只需编写一次共享代码，**FastAPI** 会在你的*路径操作*中为你调用它。
-/// check | 检查
+/// tip | 提示
注意，无需创建专门的类并传给 **FastAPI** 去“注册”之类的操作。
@@ -164,7 +164,7 @@ commons: Annotated[dict, Depends(common_parameters)]
-## 简单用法 { #simple-usage }
+## 簡单用法 { #simple-usage }
观察一下就会发现，只要*路径*和*操作*匹配，就会使用声明的*路径操作函数*。随后，**FastAPI** 会用正确的参数调用该函数，并从请求中提取数据。
diff --git a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
index 1c30b43807..a57271c8e7 100644
--- a/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/zh/docs/tutorial/dependencies/sub-dependencies.md
@@ -35,7 +35,7 @@ FastAPI 支持创建含**子依赖项**的依赖项。
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
-/// info | 信息
+/// note | 注意
注意，这里在*路径操作函数*中只声明了一个依赖项，即 `query_or_cookie_extractor` 。
diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md
index 78db1fefc0..3eee0d44fd 100644
--- a/docs/zh/docs/tutorial/first-steps.md
+++ b/docs/zh/docs/tutorial/first-steps.md
@@ -180,7 +180,7 @@ entrypoint = "backend.main:app"
from backend.main import app
```
-### `fastapi dev` 带路径 { #fastapi-dev-with-path }
+### 带路径或使用 `--entrypoint` CLI 选项的 `fastapi dev` { #fastapi-dev-with-path-or-with-entrypoint-cli-option }
你也可以把文件路径传给 `fastapi dev` 命令，它会尝试推断要使用的 FastAPI 应用对象：
@@ -188,29 +188,19 @@ from backend.main import app
$ fastapi dev main.py
```
-但这样每次调用 `fastapi` 命令时都需要记得传入正确的路径。
-
-另外，其他工具可能无法找到它，例如 [VS Code 扩展](../editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。
-
-### 部署你的应用（可选） { #deploy-your-app-optional }
-
-你可以选择将 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)，如果还没有，先去加入候补名单。🚀
-
-如果你已经拥有 **FastAPI Cloud** 账户（我们从候补名单邀请了你 😉），你可以用一条命令部署应用。
-
-部署前，先确保已登录：
-
-
+或者，你也可以给 `fastapi dev` 命令传入 `--entrypoint` 选项：
```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud 🚀
+$ fastapi dev --entrypoint main:app
```
-
+但这样每次调用 `fastapi` 命令时都需要记得传入正确的路径/entrypoint。
+
+另外，其他工具可能无法找到它，例如 [VS Code 扩展](../editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com)，因此推荐在 `pyproject.toml` 中使用 `entrypoint`。
+
+### 部署你的应用（可选） { #deploy-your-app-optional }
-然后部署你的应用：
+你可以选择用一条命令将 FastAPI 应用部署到 [FastAPI Cloud](https://fastapicloud.com)。🚀
@@ -226,6 +216,8 @@ Deploying to FastAPI Cloud...
+CLI 会自动检测你的 FastAPI 应用并将其部署到云端。如果你尚未登录，浏览器会打开以完成认证流程。
+
就这些！现在你可以通过该 URL 访问你的应用了。✨
## 分步概括 { #recap-step-by-step }
@@ -270,7 +262,7 @@ https://example.com/items/foo
/items/foo
```
-/// info
+/// note | 注意
「路径」也通常被称为「端点」或「路由」。
@@ -322,7 +314,7 @@ https://example.com/items/foo
* 请求路径为 `/`
* 使用 get 操作
-/// info | `@decorator` 信息
+/// note | `@decorator` 信息
`@something` 语法在 Python 中被称为「装饰器」。
@@ -349,7 +341,7 @@ https://example.com/items/foo
* `@app.patch()`
* `@app.trace()`
-/// tip
+/// tip | 提示
你可以随意使用任何一个操作（HTTP方法）。
@@ -383,7 +375,7 @@ https://example.com/items/foo
{* ../../docs_src/first_steps/tutorial003_py310.py hl[7] *}
-/// note
+/// note | 注意
如果你不知道两者的区别，请查阅 [并发: *赶时间吗？*](../async.md#in-a-hurry)。
diff --git a/docs/zh/docs/tutorial/metadata.md b/docs/zh/docs/tutorial/metadata.md
index b761f08886..ba480637b3 100644
--- a/docs/zh/docs/tutorial/metadata.md
+++ b/docs/zh/docs/tutorial/metadata.md
@@ -74,7 +74,7 @@
{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}
-/// info | 信息
+/// note | 注意
阅读更多关于标签的信息[路径操作配置](path-operation-configuration.md#tags)。
diff --git a/docs/zh/docs/tutorial/path-operation-configuration.md b/docs/zh/docs/tutorial/path-operation-configuration.md
index b9046a13be..b813e38f80 100644
--- a/docs/zh/docs/tutorial/path-operation-configuration.md
+++ b/docs/zh/docs/tutorial/path-operation-configuration.md
@@ -56,7 +56,7 @@ OpenAPI 概图会自动添加标签，供 API 文档接口使用：
## 从 docstring 获取描述 { #description-from-docstring }
-描述内容比较长且占用多行时，可以在函数的 docstring 中声明*路径操作*的描述，**FastAPI** 会从中读取。
+描述内容比较长且占用多行时，可以在函数的 文档字符串 中声明*路径操作*的描述，**FastAPI** 会从中读取。
文档字符串支持 [Markdown](https://en.wikipedia.org/wiki/Markdown)，能正确解析和显示 Markdown 的内容，但要注意文档字符串的缩进。
@@ -72,13 +72,13 @@ OpenAPI 概图会自动添加标签，供 API 文档接口使用：
{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}
-/// info | 信息
+/// note | 注意
注意，`response_description` 只用于描述响应，`description` 一般则用于描述*路径操作*。
///
-/// check | 检查
+/// tip | 提示
OpenAPI 规定每个*路径操作*都要有响应描述。
diff --git a/docs/zh/docs/tutorial/path-params-numeric-validations.md b/docs/zh/docs/tutorial/path-params-numeric-validations.md
index 26b91c1d73..cb4985119c 100644
--- a/docs/zh/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/zh/docs/tutorial/path-params-numeric-validations.md
@@ -8,7 +8,7 @@
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-/// info | 信息
+/// note | 注意
FastAPI 在 0.95.0 版本添加了对 `Annotated` 的支持（并开始推荐使用它）。
@@ -131,7 +131,7 @@ Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数
* `lt`：小于（`l`ess `t`han）
* `le`：小于等于（`l`ess than or `e`qual）
-/// info | 信息
+/// note | 注意
`Query`、`Path` 以及你后面会看到的其他类，都是一个通用 `Param` 类的子类。
@@ -139,7 +139,7 @@ Python 不会对这个 `*` 做任何事，但它会知道之后的所有参数
///
-/// note | 注意
+/// note | 技术细节
当你从 `fastapi` 导入 `Query`、`Path` 和其他对象时，它们实际上是函数。
diff --git a/docs/zh/docs/tutorial/path-params.md b/docs/zh/docs/tutorial/path-params.md
index df9210673c..0db71859cc 100644
--- a/docs/zh/docs/tutorial/path-params.md
+++ b/docs/zh/docs/tutorial/path-params.md
@@ -20,7 +20,7 @@
本例把 `item_id` 的类型声明为 `int`。
-/// check | 检查
+/// tip | 提示
类型声明将为函数提供错误检查、代码补全等编辑器支持。
@@ -34,7 +34,7 @@
{"item_id":3}
```
-/// check | 检查
+/// tip | 提示
注意，函数接收并返回的值是 `3`（ `int`），不是 `"3"`（`str`）。
@@ -66,7 +66,7 @@
值的类型不是 `int` 而是浮点数（`float`）时也会显示同样的错误，比如： [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2)
-/// check | 检查
+/// tip | 提示
**FastAPI** 使用同样的 Python 类型声明实现了数据校验。
@@ -82,7 +82,7 @@
-/// check | 检查
+/// tip | 提示
还是使用 Python 类型声明，**FastAPI** 提供了（集成 Swagger UI 的）自动交互式文档。
@@ -102,7 +102,7 @@
## Pydantic { #pydantic }
-FastAPI 充分地利用了 [Pydantic](https://docs.pydantic.dev/) 的优势，用它在后台校验数据。众所周知，Pydantic 擅长的就是数据校验。
+所有数据校验都由 [Pydantic](https://docs.pydantic.dev/) 在幕后完成，因此你能从中获得所有好处。而且你可以放心。
同样，`str`、`float`、`bool` 以及很多复合数据类型都可以使用类型声明。
diff --git a/docs/zh/docs/tutorial/query-params-str-validations.md b/docs/zh/docs/tutorial/query-params-str-validations.md
index 67a5b40008..05cefc6e25 100644
--- a/docs/zh/docs/tutorial/query-params-str-validations.md
+++ b/docs/zh/docs/tutorial/query-params-str-validations.md
@@ -29,7 +29,7 @@ FastAPI 会因为默认值 `= None` 而知道 `q` 的值不是必填的。
{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
-/// info | 信息
+/// note | 注意
FastAPI 在 0.95.0 版本中添加了对 `Annotated` 的支持（并开始推荐使用）。
@@ -381,7 +381,7 @@ Pydantic 还有 [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/va
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
-/// info | 信息
+/// note | 注意
这在 Pydantic 2 或更高版本中可用。😎
diff --git a/docs/zh/docs/tutorial/query-params.md b/docs/zh/docs/tutorial/query-params.md
index 9d6c05fbb7..c9cb2d26e1 100644
--- a/docs/zh/docs/tutorial/query-params.md
+++ b/docs/zh/docs/tutorial/query-params.md
@@ -65,7 +65,7 @@ http://127.0.0.1:8000/items/?skip=20
本例中，查询参数 `q` 是可选的，默认值为 `None`。
-/// check | 检查
+/// tip | 提示
注意，**FastAPI** 可以识别出 `item_id` 是路径参数，`q` 不是路径参数，而是查询参数。
diff --git a/docs/zh/docs/tutorial/request-files.md b/docs/zh/docs/tutorial/request-files.md
index 6569e1715a..102d422155 100644
--- a/docs/zh/docs/tutorial/request-files.md
+++ b/docs/zh/docs/tutorial/request-files.md
@@ -2,7 +2,7 @@
你可以使用 `File` 定义由客户端上传的文件。
-/// info | 信息
+/// note | 注意
要接收上传的文件，请先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。
@@ -28,7 +28,7 @@ $ pip install python-multipart
{* ../../docs_src/request_files/tutorial001_an_py310.py hl[9] *}
-/// info | 信息
+/// note | 注意
`File` 是直接继承自 `Form` 的类。
diff --git a/docs/zh/docs/tutorial/request-form-models.md b/docs/zh/docs/tutorial/request-form-models.md
index ec52710a8f..bbe805ef88 100644
--- a/docs/zh/docs/tutorial/request-form-models.md
+++ b/docs/zh/docs/tutorial/request-form-models.md
@@ -2,7 +2,7 @@
你可以在 FastAPI 中使用 **Pydantic 模型**声明**表单字段**。
-/// info | 信息
+/// note | 注意
要使用表单，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。
diff --git a/docs/zh/docs/tutorial/request-forms-and-files.md b/docs/zh/docs/tutorial/request-forms-and-files.md
index 8e092af0a8..d972391368 100644
--- a/docs/zh/docs/tutorial/request-forms-and-files.md
+++ b/docs/zh/docs/tutorial/request-forms-and-files.md
@@ -2,7 +2,7 @@
FastAPI 支持同时使用 `File` 和 `Form` 定义文件和表单字段。
-/// info | 信息
+/// note | 注意
接收上传的文件和/或表单数据，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。
diff --git a/docs/zh/docs/tutorial/request-forms.md b/docs/zh/docs/tutorial/request-forms.md
index ab82a181a2..3d305779f8 100644
--- a/docs/zh/docs/tutorial/request-forms.md
+++ b/docs/zh/docs/tutorial/request-forms.md
@@ -2,7 +2,7 @@
当你需要接收表单字段而不是 JSON 时，可以使用 `Form`。
-/// info
+/// note
要使用表单，首先安装 [`python-multipart`](https://github.com/Kludex/python-multipart)。
@@ -32,7 +32,7 @@ $ pip install python-multipart
使用 `Form` 可以像使用 `Body`（以及 `Query`、`Path`、`Cookie`）一样声明相同的配置，包括校验、示例、别名（例如将 `username` 写成 `user-name`）等。
-/// info
+/// note
`Form` 是直接继承自 `Body` 的类。
diff --git a/docs/zh/docs/tutorial/response-model.md b/docs/zh/docs/tutorial/response-model.md
index 9b4e0382e9..5d8d0c1859 100644
--- a/docs/zh/docs/tutorial/response-model.md
+++ b/docs/zh/docs/tutorial/response-model.md
@@ -72,7 +72,7 @@ FastAPI 会使用这个 `response_model` 来完成数据文档、校验等，并
{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
-/// info | 信息
+/// note | 注意
要使用 `EmailStr`，首先安装 [`email-validator`](https://github.com/JoshData/python-email-validator)。
@@ -116,7 +116,7 @@ $ pip install "pydantic[email]"
{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
-……我们仍将 `response_model` 声明为不包含密码的 `UserOut` 模型：
+...我们仍将 `response_model` 声明为不包含密码的 `UserOut` 模型：
{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
@@ -128,7 +128,7 @@ $ pip install "pydantic[email]"
这就是为什么在这个例子里我们必须在 `response_model` 参数中声明它。
-……但继续往下读，看看如何更好地处理这种情况。
+...但继续往下读，看看如何更好地处理这种情况。
## 返回类型与数据过滤 { #return-type-and-data-filtering }
@@ -206,7 +206,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承
{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
-……它失败是因为该类型注解不是 Pydantic 类型，也不只是单个 `Response` 类或其子类，而是 `Response` 与 `dict` 的联合类型（任意其一）。
+...它失败是因为该类型注解不是 Pydantic 类型，也不只是单个 `Response` 类或其子类，而是 `Response` 与 `dict` 的联合类型（任意其一）。
### 禁用响应模型 { #disable-response-model }
@@ -251,7 +251,7 @@ FastAPI 在内部配合 Pydantic 做了多项处理，确保不会把类继承
}
```
-/// info | 信息
+/// note | 注意
你还可以使用：
diff --git a/docs/zh/docs/tutorial/response-status-code.md b/docs/zh/docs/tutorial/response-status-code.md
index e57c0e5937..411ece71c1 100644
--- a/docs/zh/docs/tutorial/response-status-code.md
+++ b/docs/zh/docs/tutorial/response-status-code.md
@@ -18,7 +18,7 @@
`status_code` 参数接收表示 HTTP 状态码的数字。
-/// info | 信息
+/// note | 注意
`status_code` 还能接收 `IntEnum` 类型，比如 Python 的 [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus)。
diff --git a/docs/zh/docs/tutorial/schema-extra-example.md b/docs/zh/docs/tutorial/schema-extra-example.md
index 482abd21de..2ea590c868 100644
--- a/docs/zh/docs/tutorial/schema-extra-example.md
+++ b/docs/zh/docs/tutorial/schema-extra-example.md
@@ -24,7 +24,7 @@
///
-/// info | 信息
+/// note | 注意
OpenAPI 3.1.0（自 FastAPI 0.99.0 起使用）增加了对 `examples` 的支持，它是 JSON Schema 标准的一部分。
@@ -155,7 +155,7 @@ OpenAPI 还在规范的其他部分添加了 `example` 和 `examples` 字段：
- `File()`
- `Form()`
-/// info | 信息
+/// note | 注意
这个旧的、OpenAPI 特定的 `examples` 参数，自 FastAPI `0.103.0` 起改名为 `openapi_examples`。
@@ -171,7 +171,7 @@ OpenAPI 还在规范的其他部分添加了 `example` 和 `examples` 字段：
JSON Schema 中这个新的 `examples` 字段只是一个由示例组成的 `list`，而不是像上面提到的 OpenAPI 其他位置那样带有额外元数据的 `dict`。
-/// info | 信息
+/// note | 注意
即使在 OpenAPI 3.1.0 发布、并与 JSON Schema 有了这种更简单的集成之后，有一段时间里，提供自动文档的 Swagger UI 并不支持 OpenAPI 3.1.0（它自 5.0.0 版本起已支持 🎉）。
diff --git a/docs/zh/docs/tutorial/security/first-steps.md b/docs/zh/docs/tutorial/security/first-steps.md
index 6cc91211a3..e274d513a4 100644
--- a/docs/zh/docs/tutorial/security/first-steps.md
+++ b/docs/zh/docs/tutorial/security/first-steps.md
@@ -24,13 +24,13 @@
## 运行 { #run-it }
-/// info | 信息
+/// note | 注意
当你使用命令 `pip install "fastapi[standard]"` 安装 **FastAPI** 时，[`python-multipart`](https://github.com/Kludex/python-multipart) 包会自动安装。
但是，如果你使用 `pip install fastapi`，默认不会包含 `python-multipart` 包。
-如需手动安装，请先创建并激活[虚拟环境](../../virtual-environments.md)，然后执行：
+如需手动安装，请先创建[虚拟环境](../../virtual-environments.md)、激活它，然后执行：
```console
$ pip install python-multipart
@@ -60,7 +60,7 @@ $ fastapi dev
-/// check | Authorize 按钮！
+/// tip | Authorize 按钮！
页面右上角已经有一个崭新的“Authorize”按钮。
@@ -118,7 +118,7 @@ OAuth2 的设计目标是让后端或 API 与负责用户认证的服务器解
本示例将使用 **OAuth2** 的 **Password** 流程并配合 **Bearer** 令牌，通过 `OAuth2PasswordBearer` 类来实现。
-/// info | 信息
+/// note | 注意
“Bearer” 令牌并非唯一选项。
@@ -148,7 +148,7 @@ OAuth2 的设计目标是让后端或 API 与负责用户认证的服务器解
我们很快也会创建对应的实际路径操作。
-/// info | 信息
+/// note | 注意
如果你是非常严格的 “Pythonista”，可能不喜欢使用参数名 `tokenUrl` 而不是 `token_url`。
@@ -176,7 +176,7 @@ oauth2_scheme(some, parameters)
**FastAPI** 会据此在 OpenAPI 架构（以及自动生成的 API 文档）中定义一个“安全方案”。
-/// info | 技术细节
+/// note | 技术细节
**FastAPI** 之所以知道可以使用（在依赖中声明的）`OAuth2PasswordBearer` 在 OpenAPI 中定义安全方案，是因为它继承自 `fastapi.security.oauth2.OAuth2`，而后者又继承自 `fastapi.security.base.SecurityBase`。
diff --git a/docs/zh/docs/tutorial/security/get-current-user.md b/docs/zh/docs/tutorial/security/get-current-user.md
index 814ff2c822..e8a1de9d5a 100644
--- a/docs/zh/docs/tutorial/security/get-current-user.md
+++ b/docs/zh/docs/tutorial/security/get-current-user.md
@@ -53,7 +53,7 @@
///
-/// check | 检查
+/// tip | 提示
依赖系统的这种设计方式可以支持不同的依赖项返回同一个 `User` 模型。
diff --git a/docs/zh/docs/tutorial/security/oauth2-jwt.md b/docs/zh/docs/tutorial/security/oauth2-jwt.md
index 8a56137d37..e0cbdf685e 100644
--- a/docs/zh/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/zh/docs/tutorial/security/oauth2-jwt.md
@@ -42,7 +42,7 @@ $ pip install pyjwt
-/// info | 信息
+/// note | 注意
如果你计划使用类似 RSA 或 ECDSA 的数字签名算法，你应该安装加密库依赖项 `pyjwt[crypto]`。
@@ -213,7 +213,7 @@ JWT 除了用于识别用户并允许其直接在你的 API 上执行操作之
用户名: `johndoe`
密码: `secret`
-/// check | 检查
+/// tip | 提示
注意，代码中的任何地方都没有明文密码 “`secret`”，我们只有它的哈希版本。
diff --git a/docs/zh/docs/tutorial/security/simple-oauth2.md b/docs/zh/docs/tutorial/security/simple-oauth2.md
index d8d5b561e0..6ebf77e36f 100644
--- a/docs/zh/docs/tutorial/security/simple-oauth2.md
+++ b/docs/zh/docs/tutorial/security/simple-oauth2.md
@@ -32,7 +32,7 @@ OAuth2 还支持客户端发送**`scope`**表单字段。
* 脸书和 Instagram 使用 `instagram_basic`
* 谷歌使用 `https://www.googleapis.com/auth/drive`
-/// info | 信息
+/// note | 注意
OAuth2 中，**作用域**只是声明指定权限的字符串。
@@ -72,7 +72,7 @@ OAuth2 中，**作用域**只是声明指定权限的字符串。
* 可选的 `client_id`（本例未使用）
* 可选的 `client_secret`（本例未使用）
-/// info | 信息
+/// note | 注意
`OAuth2PasswordRequestForm` 并不像 `OAuth2PasswordBearer` 那样是 **FastAPI** 的特殊类。
@@ -144,7 +144,7 @@ UserInDB(
)
```
-/// info | 信息
+/// note | 注意
`user_dict` 的说明，详见[**更多模型**一章](../extra-models.md#about-user-in-dict)。
@@ -196,7 +196,7 @@ UserInDB(
{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
-/// info | 信息
+/// note | 注意
此处返回值为 `Bearer` 的响应头 `WWW-Authenticate` 也是规范的一部分。
diff --git a/docs/zh/docs/tutorial/server-sent-events.md b/docs/zh/docs/tutorial/server-sent-events.md
index c78562b91e..8542756f21 100644
--- a/docs/zh/docs/tutorial/server-sent-events.md
+++ b/docs/zh/docs/tutorial/server-sent-events.md
@@ -4,7 +4,7 @@
这类似于[流式传输 JSON Lines](stream-json-lines.md)，但使用 `text/event-stream` 格式，浏览器原生通过 [`EventSource` API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) 支持。
-/// info | 信息
+/// note | 注意
新增于 FastAPI 0.135.0。
diff --git a/docs/zh/docs/tutorial/stream-json-lines.md b/docs/zh/docs/tutorial/stream-json-lines.md
index 8a27dce760..e980225011 100644
--- a/docs/zh/docs/tutorial/stream-json-lines.md
+++ b/docs/zh/docs/tutorial/stream-json-lines.md
@@ -2,7 +2,7 @@
当你想以“流”的方式发送一系列数据时，可以使用 JSON Lines。
-/// info | 信息
+/// note | 注意
新增于 FastAPI 0.134.0。
@@ -48,7 +48,7 @@ sequenceDiagram
它与 JSON 数组（相当于 Python 的 list）非常相似，但不是用 `[]` 包裹、并在各项之间使用 `,` 分隔，而是每行一个 JSON 对象，彼此以换行符分隔。
-/// info | 信息
+/// note | 注意
关键在于你的应用可以逐行生成数据，而客户端在消费前面的行。
diff --git a/docs/zh/docs/tutorial/testing.md b/docs/zh/docs/tutorial/testing.md
index 6607a12391..50e1d8f2de 100644
--- a/docs/zh/docs/tutorial/testing.md
+++ b/docs/zh/docs/tutorial/testing.md
@@ -8,7 +8,7 @@
## 使用 `TestClient` { #using-testclient }
-/// info | 信息
+/// note | 注意
要使用 `TestClient`，先要安装 [`httpx`](https://www.python-httpx.org)。
@@ -142,7 +142,7 @@ $ pip install httpx
关于如何传数据给后端的更多信息（使用 `httpx` 或 `TestClient`），请查阅 [HTTPX 文档](https://www.python-httpx.org)。
-/// info | 信息
+/// note | 注意
注意 `TestClient` 接收可以被转化为JSON的数据，而不是Pydantic模型。
