FastAPI 学习之路（三十七）元数据和文档 URL

你可以在 FastAPI 应用中自定义几个元数据配置。

你可以设定：

• Title：在 OpenAPI 和自动 API 文档用户界面中作为 API 的标题/名称使用。

• Description：在 OpenAPI 和自动 API 文档用户界面中用作 API 的描述。

• Version：API 版本，例如 v2 或者 2.5.0。

• 如果你之前的应用程序版本也使用 OpenAPI 会很有用。

我们看下如何使用的

description = """
用户创建和items创建
## Items

你可以读他们

## Users

你可以做下面的:

* **创建用户**
* **读取用户** .
"""

app = FastAPI(
    title="系统接口",
    description=description,
    version="0.0.1"
)

我们看下实现后的效果，

你也可以使用参数 openapi_tags，为用于分组路径操作的不同标签添加额外的元数据。

它接受一个列表，这个列表包含每个标签对应的一个字典。

每个字典可以包含：

• name（必要）：一个 str，它与路径操作和 APIRouter 中使用的 tags 参数有相同的标签名。

• description：一个用于简短描述标签的 str。它支持 Markdown 并且会在文档用户界面中显示。

• externalDocs：一个描述外部文档的 dict：

• description：用于简短描述外部文档的 str。

• url（必要）：外部文档的 URL str。

使用方式

from fastapi import FastAPI
from routers.user import usersRouter
from routers.items import itemsRouter

tags_metadata = [
    {
        "name": "系统接口",
        "description": """
用户创建和items创建
"""},
    {
        "name": "items",
        "description": "管理items，你可以查看文档",
        "externalDocs": {
            "description": "使用文档",
            "url": "http://localhost:8000/docs#/Itmes",
        },
    },
]

app = FastAPI(
    openapi_tags=tags_metadata
)
app.include_router(usersRouter, prefix="/user", tags=['users'])
app.include_router(itemsRouter, prefix="/items", tags=['Itmes'])

最后的效果

文档 URLs

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

• Swagger UI：服务于 /docs。

• 可以使用参数 docs_url 设置它的 URL。

• 可以通过设置 docs_url=None 禁用它。

• ReDoc：服务于 /redoc。

• 可以使用参数 redoc_url 设置它的 URL。

• 可以通过设置 redoc_url=None 禁用它。

我们一直没有看过redoc，我们今天看下

我们重新定义下对应的文档的地址

app = FastAPI(
    openapi_tags=tags_metadata,
    docs_url="/openapi",
    redoc_url="/apidoc"
)

我们启动后看下。

必须要访问新的地址

当然我们也可以禁用，可以根据我们的需求来。

文章首发在公众号，欢迎关注。