元数据和文档 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 字段

参数	类型	描述
`name`	`str`	联系人/组织的识别名称。
`url`	`str`	指向联系信息的 URL。必须是 URL 格式。
`email`	`str`	联系人/组织的电子邮件地址。必须是电子邮件格式。

license_info

dict

暴露的 API 的许可证信息。可以包含多个字段。

license_info 字段

参数	类型	描述
`name`	`str`	必需 (如果设置了 `license_info`)。API 使用的许可证名称。
`identifier`	`str`	API 的 SPDX 许可证表达式。`identifier` 字段与 `url` 字段互斥。适用于 OpenAPI 3.1.0, FastAPI 0.99.0。
`url`	`str`	API 使用的许可证的 URL。必须是 URL 格式。

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

Python 3.9+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://apache.ac.cn/licenses/LICENSE-2.0.html",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

提示

您可以在 description 字段中编写 Markdown，它将在输出中渲染。

通过此配置，自动 API 文档将如下所示：

许可证标识符¶

自 OpenAPI 3.1.0 和 FastAPI 0.99.0 起，您还可以使用 identifier 而不是 url 来设置 license_info。

例如

Python 3.9+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "identifier": "MIT",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

标签元数据¶

您还可以为用于使用 openapi_tags 参数对路径操作进行分组的各个标签添加其他元数据。

它接受一个列表，其中包含每个标签的一个字典。

每个字典可以包含：

name (必需)：一个 str，包含您在路径操作和 APIRouter 的 tags 参数中使用的相同标签名称。
description：一个 str，包含标签的简短描述。它可以包含 Markdown，并且将在文档 UI 中显示。
externalDocs：一个 dict，描述外部文档，包含：
- description：一个 str，包含外部文档的简短描述。
- url (必需)：一个 str，包含外部文档的 URL。

创建标签元数据¶

让我们通过一个使用 users 和 items 标签的示例来尝试一下。

为您的标签创建元数据，并将其传递给 openapi_tags 参数。

Python 3.9+

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.org.cn/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

请注意，您可以在描述中使用 Markdown，例如，“login”将显示为粗体（login），“fancy”将显示为斜体（fancy）。

提示

您不必为所有使用的标签都添加元数据。

使用您的标签¶

在您的路径操作（和 APIRouter）中使用 tags 参数将它们分配给不同的标签。

Python 3.9+

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.org.cn/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

信息

在路径操作配置中阅读有关标签的更多信息。

检查文档¶

现在，如果您查看文档，它们将显示所有额外的元数据。

标签顺序¶

每个标签元数据字典的顺序也决定了它们在文档 UI 中的显示顺序。

例如，尽管 users 在字母顺序上应该排在 items 之后，但它显示在 items 之前，因为我们将它们的元数据添加为列表中的第一个字典。

OpenAPI URL¶

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

但是您可以使用 openapi_url 参数进行配置。

例如，将其设置为在 /api/v1/openapi.json 提供：

Python 3.9+

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

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

文档 URL¶

您可以配置包含的两个文档用户界面：

Swagger UI：位于 /docs。
- 您可以使用 docs_url 参数设置其 URL。
- 您可以通过设置 docs_url=None 来禁用它。
ReDoc：位于 /redoc。
- 您可以使用 redoc_url 参数设置其 URL。
- 您可以通过设置 redoc_url=None 来禁用它。

例如，要将 Swagger UI 设置在 /documentation 提供并禁用 ReDoc：

Python 3.9+

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]