元数据和文档 URL¶

FastAPI 支持多种自定义元数据配置。

API 元数据¶

您可以设置如下用于 OpenAPI 规范与 API 文档的字段：

参数类型说明

title 字符串 API 标题。

description 字符串 API 的简要描述，可使用 Markdown。

version 字符串 API 的版本。这是您的应用的版本，不是 OpenAPI 的版本。例如 2.5.0。

terms_of_service 字符串 API 服务条款的 URL。如果提供了服务条款，这个字段必须是 URL。

contact

字典

显示 API 的联系信息。包含以下字段。

contact 字段

参数	类型	说明
`name`	`str`	联系人或机构的名称。
`url`	`str`	指向联系信息的 URL。必须是 URL 格式。
`email`	`str`	联系人或机构的电子邮件。必须是电子邮件格式。

license_info

字典

显示 API 的协议信息。包含以下字段。

license_info fields

参数	类型	说明
`name`	`str`	必填项（如果设置了 `license_info`）。API 使用的协议名称。
`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,
    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://www.apache.org/licenses/LICENSE-2.0.html",
    },
)


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

提示

description 字段支持 Markdown，并且在输出结果里渲染。

设置后，API 文档显示如下：

标签元数据¶

参数 openapi_tags 可以为不同路径操作的标签添加更多元数据。

openapi_tags 接收包含标签字典的列表。

这个字典包含以下数据：

name（必选）： str，与路径操作和 APIRouter 中的 tags 参数的名称相同
description：str，标签的简明描述，支持 Markdown，并且在 API 文档中显示
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.tiangolo.com/",
        },
    },
]

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"}]

注意，description 支持 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.tiangolo.com/",
        },
    },
]

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"}]

说明

有关标签的详情，请参阅路径操作配置。

查看文档¶

APi 文档中会显示所有附加的元数据：

标签顺序¶

标签元数据字典的顺序定义了标签在文档中的显示顺序。

例如，即使按字母顺序 users 应在 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_url 参数设置为 None，即可完全禁用 OpenAPI 概图，但同样也会禁用 API 文档。

文档 URL¶

同样，也可以配置两个内置的 API 文档，包括：

Swagger UI：地址为 /docs：
- docs_url 用于设置 URL
- docs_url=None，禁用 Swagger
ReDoc：地址为 /redoc：
- redoc_url 用于设置 URL
- redoc_url=None，禁用 ReDoc

例如，把 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"}]