自定义 API 文档
虽然 FastAPI 可以自动生成 API 文档，但有时您可能需要自定义文档的某些部分。为此，FastAPI 提供了一种方式来扩展自动生成的文档。
您可以通过创建一个 OpenAPI 文档对象来扩展自动生成的文档。您可以在此对象上添加标签、安全定义、服务器等信息。此外，您还可以使用 FastAPI 提供的几个装饰器来自定义每个路由的操作。
下面是一个自定义 API 文档的示例：
代码语言：javascript复制from fastapi import FastAPI, Body, Header, HTTPException
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.openapi.utils import get_openapi
from fastapi.responses import HTMLResponse
app = FastAPI()
@app.get("/", tags=["root"])
async def root():
"""
Root endpoint that returns a welcome message.
## Response
- `200 OK` - If the request was successful
"""
return {"message": "Hello World"}
@app.get("/items/{item_id}", tags=["items"])
async def read_item(
item_id: int,
q: str = None,
user_agent: str = Header(None),
x_token: str = Header(None),
):
"""
Endpoint that returns item information.
Parameters:
- item_id (int): The ID of the item to retrieve.
- q (str): An optional query parameter.
- user_agent (str): The user agent string of the client making the request.
- x_token (str): The X-Token header value.
## Response
- `200 OK` - If the request was successful
- `404 Not Found` - If the specified item was not found
"""
if item_id == 42:
return {"item_id": item_id, "q": q, "user_agent": user_agent, "x_token": x_token}
else:
raise HTTPException(status_code=404, detail="Item not found")
@app.get("/docs", response_class=HTMLResponse)
async def custom_swagger_ui_html():
"""
Custom Swagger UI HTML.
"""
return get_swagger_ui_html(
openapi_url="/openapi.json",
title="Custom Swagger UI HTML",
oauth2_redirect_url="http://localhost:8000/docs/oauth2-redirect",
)
def custom_openapi():
"""
Custom OpenAPI.
"""
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom OpenAPI",
version="1.0.0",
description="This is a custom OpenAPI schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://img.yuanmabao.com/zijie/pic/2023/05/07/agt00tcol41.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi在上面的代码中，我们首先定义了两个路由，用于显示根路径和 /items/{item_id} 路径的信息。我们还定义了一个自定义的 Swagger UI HTML 路由和一个自定义的 OpenAPI 文档路由。
路由中，我们使用了 FastAPI 提供的 @app.get 装饰器，并使用 tags 参数为每个路由添加标签。这些标签将在自动生成的文档中显示为“分类”。
我们还定义了一些路由参数，并在函数定义的下方使用 Markdown 语法为这些参数添加了说明文档。这些文档将在自动生成的文档中显示为“请求参数”。
在 /docs 路由中，我们使用了 response_class=HTMLResponse 参数来指示 FastAPI 返回一个 HTMLResponse 对象而不是 JSON 响应。我们还使用了 FastAPI 提供的 get_swagger_ui_html 函数来生成自定义的 Swagger UI HTML。
在 custom_openapi 函数中，我们使用了 FastAPI 提供的 get_openapi 函数来生成自定义的 OpenAPI 文档。我们还使用了 x-logo 扩展属性来指定一个自定义的徽标。最后，我们将自定义的 OpenAPI 文档保存在 app.openapi_schema 中，以便在应用程序启动时使用。
