From 821a161e923ea95af6dbb01bb48867104c3bdbd6 Mon Sep 17 00:00:00 2001 From: JackLee <280147597@qq.com> Date: Mon, 4 Mar 2024 20:55:17 +0800 Subject: [PATCH 1/2] Update Chinese translation for docs/zh/docs/tutorial/query-params.md --- docs/zh/docs/tutorial/query-params.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/zh/docs/tutorial/query-params.md b/docs/zh/docs/tutorial/query-params.md index b1668a2d2523f..a0cc7fea39310 100644 --- a/docs/zh/docs/tutorial/query-params.md +++ b/docs/zh/docs/tutorial/query-params.md @@ -63,9 +63,18 @@ http://127.0.0.1:8000/items/?skip=20 通过同样的方式，你可以将它们的默认值设置为 `None` 来声明可选查询参数： -```Python hl_lines="7" -{!../../../docs_src/query_params/tutorial002.py!} -``` +=== "Python 3.10+" + + ```Python hl_lines="7" + {!> ../../../docs_src/query_params/tutorial002_py310.py!} + ``` + +=== "Python 3.8+" + + ```Python hl_lines="9" + {!> ../../../docs_src/query_params/tutorial002.py!} + ``` + 在这个例子中，函数参数 `q` 将是可选的，并且默认值为 `None`。 From 445bbb7675ace82afd16ed56bd353e34b0a6e0c5 Mon Sep 17 00:00:00 2001 From: JackLee <280147597@qq.com> Date: Thu, 14 Mar 2024 00:18:49 +0800 Subject: [PATCH 2/2] Update Chinese translation for docs/zh/docs/tutorial/metadata.md --- docs/zh/docs/tutorial/metadata.md | 37 +++++++++++++------------------ 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/docs/zh/docs/tutorial/metadata.md b/docs/zh/docs/tutorial/metadata.md index 3e669bc72fa24..09b106273c58c 100644 --- a/docs/zh/docs/tutorial/metadata.md +++ b/docs/zh/docs/tutorial/metadata.md @@ -1,40 +1,35 @@ # 元数据和文档 URL +你可以在 FastAPI 应用程序中自定义多个元数据配置。 -你可以在 **FastAPI** 应用中自定义几个元数据配置。 +## API 元数据 -## 标题、描述和版本 +你可以在设置 OpenAPI 规范和自动 API 文档 UI 中使用的以下字段： -你可以设定： +| 参数 | 类型 | 描述 | +|------------|------|-------------| +| `title` | `str` | API 的标题。 | +| `summary` | `str` | API 的简短摘要。 自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。. | +| `description` | `str` | API 的简短描述。可以使用Markdown。 | +| `version` | `string` | API 的版本。这是您自己的应用程序的版本，而不是 OpenAPI 的版本。例如 `2.5.0` 。 | +| `terms_of_service` | `str` | API 服务条款的 URL。如果提供，则必须是 URL。 | +| `contact` | `dict` | 公开的 API 的联系信息。它可以包含多个字段。
contact 字段
参数Type描述
namestr联系人/组织的识别名称。
urlstr指向联系信息的 URL。必须采用 URL 格式。
emailstr联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。
| +| `license_info` | `dict` | 公开的 API 的许可证信息。它可以包含多个字段。
license_info 字段
参数类型描述
namestr必须的 (如果设置了license_info). 用于 API 的许可证名称。
identifierstr一个API的SPDX许可证表达。 The identifier field is mutually exclusive of the url field. 自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。
urlstr用于 API 的许可证的 URL。必须采用 URL 格式。
| -* **Title**：在 OpenAPI 和自动 API 文档用户界面中作为 API 的标题/名称使用。 -* **Description**：在 OpenAPI 和自动 API 文档用户界面中用作 API 的描述。 -* **Version**：API 版本，例如 `v2` 或者 `2.5.0`。 - * 如果你之前的应用程序版本也使用 OpenAPI 会很有用。 - -使用 `title`、`description` 和 `version` 来设置它们： +你可以按如下方式设置它们： ```Python hl_lines="4-6" {!../../../docs_src/metadata/tutorial001.py!} ``` +!!! tip + 您可以在 `description` 字段中编写 Markdown，它将在输出中呈现。 + 通过这样设置，自动 API 文档看起来会像： ## 标签元数据 -你也可以使用参数 `openapi_tags`，为用于分组路径操作的不同标签添加额外的元数据。 - -它接受一个列表，这个列表包含每个标签对应的一个字典。 - -每个字典可以包含： - -* `name`（**必要**）：一个 `str`，它与*路径操作*和 `APIRouter` 中使用的 `tags` 参数有相同的标签名。 -* `description`：一个用于简短描述标签的 `str`。它支持 Markdown 并且会在文档用户界面中显示。 -* `externalDocs`：一个描述外部文档的 `dict`： - * `description`：用于简短描述外部文档的 `str`。 - * `url`（**必要**）：外部文档的 URL `str`。 - ### 创建标签元数据 让我们在带有标签的示例中为 `users` 和 `items` 试一下。