FlaskAPI-交互式文档与includ_router

1 FastAPI 交互式 API 文档

FastAPI 提供了内置的交互式 API 文档，使开发者能够轻松了解和测试 API 的各个端点。这个文档是自动生成的，基于 OpenAPI 规范，支持 Swagger UI 和 ReDoc 两种交互式界面。通过 FastAPI 的交互式 API 文档，开发者能够更轻松地理解和使用 API，提高开发效率在运行 FastAPI 应用时，Uvicorn 同时启动了交互式 API 文档服务。

默认情况下，你可以通过访问 http://127.0.0.1:8000/docs 来打开 Swagger UI 风格的文档：

2 路径操作装饰器

装饰器位置：路径操作装饰器位于函数定义的上方，用于将函数与特定的 HTTP 请求路径和方法关联起来。一般形式：@app.请求方法("路径")，其中app是ASGI 应用对象，请求方法可以是get、post、put、delete等 HTTP 请求方法，路径是一个字符串，表示请求的 URL 路径。如下：

python 复制代码

app = FastAPI()

@app.get("/")
def get_user():
    return {"Hello": "World"}

@app.post("/")
def set_user():
    return {"Hello": "World"}

@app.put("/")
def put_user():
    return {"Hello": "World"}
@app.delete("/")
def delete_user():
    return {"Hello": "World"}

我们可以设置交互式API文档，比如说对端点设置分类，对端点设置摘要。

python 复制代码

@app.get("/",tags=["a"],summary="获取用户")
def get_user():
    return {"Hello": "World"}

@app.post("/",tags=["a"],summary="设置用户")
def set_user():
    return {"Hello": "World"}

@app.put("/",tags=["b"],summary="更新用户")
def put_user():
    return {"Hello": "World"}
@app.delete("/",tags=["b"],summary="删除用户")
def delete_user():
    return {"Hello": "World"}

路由装饰器部分参数

参数	描述	示例
`tags`	用于对API端点（路由）进行分类，使API文档更清晰有条理	`@app.get("/items/", tags=["Items"])`
`summary`	提供路由功能的简短摘要，显示在API文档中	`@app.get("/items/{item_id}", summary="获取指定ID的物品")`
`description`	提供路由更详细的描述信息，用于API文档	`@app.get("/items/{item_id}", description="根据提供的物品ID，从数据库或其他存储中获取对应的物品信息")`
`response_model`	指定路由返回的数据模型，用于数据验证和序列化	`@app.post("/items/", response_model=Item)`（假设`Item`是定义好的数据模型类）
`dependencies`	允许在路由中注入依赖项，如函数、数据库连接、认证中间件等，提高代码复用性和可维护性	`@app.get("/items/", dependencies=[Depends(get_db)])`（假设`get_db`是获取数据库连接的函数）

2 include_router

include_router通常用于将多个相关的路由（由 APIRouter 实例定义）整合到主应用（由 FastAPI 实例定义）中。这样做的好处是可以对路由进行模块化管理，便于大型项目中不同功能模块的路由划分与组织，使得代码结构更加清晰，各个模块的路由可以独立开发、维护和测试。

在 FastAPI 中，include_router是FastAPI应用实例（通常是app）的一个方法。基本语法是：app.include_router(router, **parameters)。其中router是一个APIRouter实例，它包含了一组相关的路由；app是FlaskAPI实例，**parameters表示可以传递多个可选参数来配置路由的行为。如下：

python 复制代码

  app.include_router(app1)
    app.include_router(app2, prefix="/good")
    uvicorn.run(app, host="127.0.0.1", port=8000)

app1,app2是两个APIRouter实例，prefix为app2中的路由都加上了/good为前缀。APIRouter对象与FlaskAPI对象相似，使用路由装饰器处理相应URI对应的请求。

常用参数

参数	语法格式	描述	示例
`prefix`	`prefix: str = ""`	为包含的`APIRouter`中的所有路由添加统一路径前缀	`app.include_router(router, prefix="/api")`，使`router`中的路由路径前加上`/api`
`tags`	`tags: List[str] = []`	给包含的`APIRouter`中的所有路由添加统一标签，用于API文档分类	`app.include_router(router, tags=["Items"])`，`router`中的路由在API文档中归到`"Items"`标签下
`dependencies`	`dependencies: List[Depends] = []`	为包含的`APIRouter`中的所有路由统一添加依赖项，如认证、权限检查等函数	`app.include_router(router, dependencies=[Depends(authenticate_user)])`，`authenticate_user`为认证函数，`router`中的路由都需先执行此认证
`responses`	`responses: Dict[int, Dict[str, Any]] = None`	为包含的`APIRouter`中的所有路由统一设置响应，用于API文档定义预期响应内容	`app.include_router(router, responses={200: {"description": "成功获取物品列表", "content": {"application/json": {"schema": {...}}}}})`，定义`200`状态码下的响应描述和内容结构