FastAPI 学习之路(三十七)元数据和文档 URL

发布于:2024-07-11 ⋅ 阅读:(17) ⋅ 点赞:(0)

实现前的效果

那么如何实现呢,第一种方式如下:

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,我们今天看下

 

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