元数据和文档 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`	一个 SPDX API 许可证表达式。该 `identifier` 字段与 `url` 字段互斥。自 OpenAPI 3.1.0，FastAPI 0.99.0 起可用。
`url`	`str`	指向用于 API 许可证的 URL。必须是 URL 格式。

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

Python 3.8+

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 设置 license_info，而不是 url。

例如：

Python 3.8+

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 字符串，其值与你在 tags 参数中使用的标签名称相同，用于你的 路径操作 和 APIRouter。
description：一个 str 字符串，用于标签的简短描述。它可以使用 Markdown，并将在文档 UI 中显示。
externalDocs：一个 dict 字典，描述外部文档，包含
- description：一个 str 字符串，用于外部文档的简短描述。
- url (必需)：一个 str 字符串，包含外部文档的 URL。

创建标签元数据¶

让我们以包含 users 和 items 标签的示例来尝试。

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

Python 3.8+

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) 分配到不同的标签

Python 3.8+

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 之后，但它会显示在它们之前，因为我们将其元数据作为列表中的第一个字典添加。

OpenAPI URL¶

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

但你可以使用参数 openapi_url 配置它。

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

Python 3.8+

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.8+

from fastapi import FastAPI

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


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