tiangolo.fastapi/docs/zh/docs/tutorial/metadata.md

元数据和文档 URL

你可以在 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 描述 name str 联系人/组织的识别名称。 url str 指向联系信息的 URL。必须采用 URL 格式。 email str 联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。
license_info	dict	公开的 API 的许可证信息。它可以包含多个字段。 license_info 字段 参数 类型 描述 name str 必须的 (如果设置了license_info). 用于 API 的许可证名称。 identifier str 一个API的SPDX许可证表达。 The identifier field is mutually exclusive of the url field. 自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。 url str 用于 API 的许可证的 URL。必须采用 URL 格式。

你可以按如下方式设置它们：

{!../../../docs_src/metadata/tutorial001.py!}

!!! tip 您可以在 description 字段中编写 Markdown，它将在输出中呈现。

通过这样设置，自动 API 文档看起来会像：

标签元数据

创建标签元数据

让我们在带有标签的示例中为 users 和 items 试一下。

创建标签元数据并把它传递给 openapi_tags 参数：

{!../../../docs_src/metadata/tutorial004.py!}

注意你可以在描述内使用 Markdown，例如「login」会显示为粗体（login）以及「fancy」会显示为斜体（fancy）。

!!! 提示 不必为你使用的所有标签都添加元数据。

使用你的标签

将 tags 参数和路径操作（以及 APIRouter）一起使用，将其分配给不同的标签：

{!../../../docs_src/metadata/tutorial004.py!}

!!! 信息 阅读更多关于标签的信息路径操作配置{.internal-link target=_blank}。

查看文档

如果你现在查看文档，它们会显示所有附加的元数据：

标签顺序

每个标签元数据字典的顺序也定义了在文档用户界面显示的顺序。

例如按照字母顺序，即使 users 排在 items 之后，它也会显示在前面，因为我们将它的元数据添加为列表内的第一个字典。

OpenAPI URL

默认情况下，OpenAPI 模式服务于 /openapi.json。

但是你可以通过参数 openapi_url 对其进行配置。

例如，将其设置为服务于 /api/v1/openapi.json：

{!../../../docs_src/metadata/tutorial002.py!}

如果你想完全禁用 OpenAPI 模式，可以将其设置为 openapi_url=None，这样也会禁用使用它的文档用户界面。

文档 URLs

你可以配置两个文档用户界面，包括：

• Swagger UI：服务于 /docs。
  • 可以使用参数 docs_url 设置它的 URL。
  • 可以通过设置 docs_url=None 禁用它。
• ReDoc：服务于 /redoc。
  • 可以使用参数 redoc_url 设置它的 URL。
  • 可以通过设置 redoc_url=None 禁用它。

例如，设置 Swagger UI 服务于 /documentation 并禁用 ReDoc：

{!../../../docs_src/metadata/tutorial003.py!}