如何将FastApi的OpenAPI文档按接口路径拆分为多个独立分组

以下两种方案都可以实现你需要的按路径前缀拆分分组的效果：

方案一：使用APIRouter实现（推荐，新项目首选） #

FastAPI原生的APIRouter支持直接指定路径前缀和分组标签，注册到主应用后，所有该路由下的接口会自动归属到对应分组，文档会按标签自动折叠展示。

from fastapi import FastAPI, APIRouter

app = FastAPI()

# 初始化books分组路由
books_router = APIRouter(
    prefix="/api/bookcollection/books",
    tags=["books"]
)
# 初始化authors分组路由
authors_router = APIRouter(
    prefix="/api/bookcollection/authors",
    tags=["authors"]
)

# 示例：books分组接口
@books_router.get("/")
def get_book_list():
    return {"data": []}

@books_router.get("/{book_id}")
def get_book_detail(book_id: int):
    return {"book_id": book_id}

# 示例：authors分组接口
@authors_router.get("/")
def get_author_list():
    return {"data": []}

# 注册两个分组路由到主应用
app.include_router(books_router)
app.include_router(authors_router)

方案二：自定义OpenAPI规则（适配已有项目，无需修改现有接口） #

如果你的接口已经全部开发完成，不想调整现有路由结构，可以通过重写OpenAPI生成方法，批量按路径前缀给接口打标签实现自动分组。

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

# 此处为你已有的所有接口，无需修改原有代码
@app.get("/api/bookcollection/books/")
def get_book_list():
    return {"data": []}

@app.get("/api/bookcollection/books/{book_id}")
def get_book_detail(book_id: int):
    return {"book_id": book_id}

@app.get("/api/bookcollection/authors/")
def get_author_list():
    return {"data": []}

# 自定义OpenAPI生成逻辑
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    # 生成基础openapi schema
    openapi_schema = get_openapi(
        title="你的文档标题",
        version="1.0.0",
        description="接口文档描述",
        routes=app.routes,
    )
    # 按路径前缀批量给接口打分组标签
    for path in openapi_schema["paths"]:
        if path.startswith("/api/bookcollection/books/"):
            for method in openapi_schema["paths"][path]:
                openapi_schema["paths"][path][method]["tags"] = ["books"]
        elif path.startswith("/api/bookcollection/authors/"):
            for method in openapi_schema["paths"][path]:
                openapi_schema["paths"][path][method]["tags"] = ["authors"]
    app.openapi_schema = openapi_schema
    return app.openapi_schema

# 替换默认的openapi生成方法
app.openapi = custom_openapi

内容的提问来源于stack exchange，提问作者jbolt