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

实现前的效果

那么如何实现呢，第一种方式如下：

from routers.items import item_router
from routers.users import user_router

"""
自定义FastApi应用中的元数据配置
    Title：在 OpenAPI 和自动 API 文档用户界面中作为 API 的标题/名称使用。
    Description：在 OpenAPI 和自动 API 文档用户界面中用作 API 的描述。
    Version：API 版本，例如 v2 或者 2.5.0。
"""

from fastapi import FastAPI


# 实现方式1
app = FastAPI(
    title="这是测试Title",
    description="这是测试description",
    version="这是测试version"
)

app.include_router(user_router, prefix="/u", tags=["users"])
app.include_router(item_router, prefix="/i", tags=["items"])

实现后的效果

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

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

每个字典可以包含：

• name（必要）：一个 str，它与路径操作和 APIRouter 中使用的 tags 参数有相同的标签名。
• description：一个用于简短描述标签的 str。它支持 Markdown 并且会在文档用户界面中显示。
• externalDocs：一个描述外部文档的 dict：

• • description：用于简短描述外部文档的 str。
  • url（必要）：外部文档的 URL str。 

使用方式

from routers.items import item_router
from routers.users import user_router

"""
自定义FastApi应用中的元数据配置
    Title：在 OpenAPI 和自动 API 文档用户界面中作为 API 的标题/名称使用。
    Description：在 OpenAPI 和自动 API 文档用户界面中用作 API 的描述。
    Version：API 版本，例如 v2 或者 2.5.0。
"""

from fastapi import FastAPI

# 实现方式2
tags_metadata = [
    {
        "name": "这类似第一种方式的title",
        "description": """这类似第一种方式的description"""
    },
    {
        "name": "items",
        "description": "创建和查找items",
        "externalDocs": {
            "description": "这是使用详细文档",
            "url": "http://localhost:8000/i/items"
        }
    }
]

app = FastAPI(
    openapi_tags=tags_metadata
)

app.include_router(user_router, prefix="/u", tags=["users"])
app.include_router(item_router, prefix="/i", tags=["items"])

实现效果如下，和第一种方式有些许区别

自定义设置文档url地址

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

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

• Swagger UI：服务于 /docs。

• • 可以使用参数 docs_url 设置它的 URL。
  • 可以通过设置 docs_url=None 禁用它。
• ReDoc：服务于 /redoc。
• • 可以使用参数 redoc_url 设置它的 URL。
  • 可以通过设置 redoc_url=None 禁用它。

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

 

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