FastAPI 如何生成 API 文档？

推荐答案

FastAPI 自动生成 API 文档，支持 Swagger UI 和 ReDoc 两种方式。默认情况下，启动 FastAPI 应用后，可以通过以下 URL 访问文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Swagger UI 提供了交互式的 API 文档界面，允许用户直接在浏览器中测试 API 端点。ReDoc 则提供了更简洁的文档展示方式，适合阅读和参考。

本题详细解读

1. 自动生成文档的原理

FastAPI 基于 OpenAPI 标准自动生成 API 文档。OpenAPI 是一个用于描述 RESTful API 的规范，FastAPI 通过分析你的代码中的路由、请求参数、响应模型等信息，自动生成符合 OpenAPI 规范的 JSON 文件。Swagger UI 和 ReDoc 都是基于这个 JSON 文件来渲染文档的。

2. 如何自定义文档

虽然 FastAPI 默认生成的文档已经非常强大，但你仍然可以通过以下方式自定义文档：

• API 元数据: 在 FastAPI 实例化时，可以通过 title、description、version 等参数来设置 API 的基本信息。

  from fastapi import FastAPI
  
  app = FastAPI(
      title="My API",
      description="This is a very fancy API",
      version="1.0.0",
  )

• 路由描述: 在定义路由时，可以通过 summary、description、response_description 等参数来为每个路由添加详细的描述。

  @app.get("/items/", summary="Get items", description="Retrieve a list of items")
  async def read_items():
      return [{"name": "Item 1"}, {"name": "Item 2"}]

• 响应模型: 通过 response_model 参数指定响应模型，FastAPI 会自动在文档中展示该模型的字段和类型。

  -- -------------------- ---- -------
  ---- -------- ------ ---------
  
  ----- ----------------
      ----- ---
      ------------ --- - ----
  
  ------------------- --------------------
  ----- --- ------------
      ------ -------- ------ -------------- -- ---- ---- ------

3. 禁用文档

如果你不希望生成文档，可以通过以下方式禁用：

from fastapi import FastAPI

app = FastAPI(docs_url=None, redoc_url=None)

4. 自定义文档路径

你也可以通过 docs_url 和 redoc_url 参数来指定文档的访问路径：

from fastapi import FastAPI

app = FastAPI(docs_url="/custom-docs", redoc_url="/custom-redoc")

这样，Swagger UI 和 ReDoc 的访问路径将分别变为 http://localhost:8000/custom-docs 和 http://localhost:8000/custom-redoc。