元数据和文档 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 字符串 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 格式。

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

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。

例如

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 参数

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）。

提示

你无需为使用的所有标签添加元数据。

使用你的标签¶

将 tags 参数与你的路径操作（和 APIRouter）一起使用，将它们分配给不同的标签

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` 中提供服务

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

from fastapi import FastAPI

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


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