FastAPI 如何为动态FastAPI端点创建Swagger文档

在本文中，我们将介绍如何为动态FastAPI端点创建Swagger文档。FastAPI是一个高性能、易于使用、可自动进行API文档生成的Python框架。通过使用FastAPI，我们可以快速开发出具备动态端点的Web应用程序，并为它们生成Swagger文档，以提供给用户或其他开发者参考和使用。

阅读更多：FastAPI 教程

FastAPI简介

FastAPI是一个基于Python，快速、可靠且易于使用的Web框架。它利用了Python的类型提示功能，可以自动验证请求的数据、请求参数和响应数据的格式。FastAPI使用了Starlette框架的高性能异步特性，因此具有出色的响应速度。另外，FastAPI也集成了Swagger UI，可以自动生成并展示API的文档。

创建动态FastAPI端点

FastAPI允许我们在运行时动态地创建和删除API端点。这在某些场景下非常有用，尤其是在我们需要根据用户输入或其他条件来动态生成端点的情况下。下面是一个示例：

from fastapi import FastAPI

app = FastAPI()

@app.get("/{item_name}")
async def retrieve_item(item_name: str):
    return {"item": item_name}

@app.delete("/{item_name}")
async def delete_item(item_name: str):
    return {"detail": f"Item {item_name} has been deleted"}

在上述示例中，我们创建了两个动态端点：retrieve_item和delete_item。它们可以接收一个item_name参数，并返回相应的结果。通过在路径中使用参数占位符{item_name}，我们可以实现动态路径匹配，并将匹配到的值传递给对应的处理函数。

为FastAPI端点创建Swagger文档

FastAPI集成了Swagger UI，它可以自动为我们的API生成文档。通过访问/docs路径，我们可以查看和测试我们的API端点。但是，对于动态端点，由于Swagger UI不知道其参数的具体取值范围，因此默认情况下无法为其生成文档。因此，我们需要手动为这些动态端点编写Swagger文档。

下面是一个为动态FastAPI端点编写Swagger文档的示例：

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

app = FastAPI()

class Item(BaseModel):
    item_name: str

@app.get("/{item_name}")
async def retrieve_item(item_name: str):
    return {"item": item_name}

@app.delete("/{item_name}")
async def delete_item(item_name: str):
    return {"detail": f"Item {item_name} has been deleted"}

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="FastAPI dynamic endpoints",
        version="0.1.0",
        routes=app.routes,
    )
    items_route = openapi_schema["paths"]["/{{item_name}}"]["get"]
    items_route["parameters"] = [{
        "name": "item_name",
        "in": "path",
        "required": True,
        "schema": {
            "type": "string",
            "enum": ["item1", "item2", "item3"]
        }
    }]
    return openapi_schema

app.openapi = custom_openapi

在上述示例中，我们使用了get_openapi方法获取了FastAPI的OpenAPI定义。然后，我们可以通过修改OpenAPI定义来为动态端点添加参数的具体取值范围。在本例中，我们为路径参数item_name添加了一个枚举类型的取值范围。

为了使自定义的OpenAPI定义能够生效，我们还需要将openapi函数赋值给app.openapi。这样，我们在访问/docs路径时将会看到我们自定义的Swagger文档。

通过以上方法，我们可以为动态FastAPI端点创建Swagger文档，并提供准确的参数取值范围。

总结

FastAPI是一款功能强大的Python Web框架，可以轻松创建动态端点。为了为这些动态端点创建Swagger文档，我们需要手动为其编写OpenAPI定义。通过修改OpenAPI定义，我们可以为动态端点添加参数的取值范围，以提供准确的文档和测试功能。FastAPI的集成Swagger UI功能使得我们可以方便地查看和测试API端点，并为开发者提供良好的参考和使用体验。