Python FastAPI Swagger|极客教程

Python FastAPI Swagger

简介

在本文中，我们将深入介绍Python中的FastAPI框架以及如何使用Swagger进行文档生成。FastAPI是一个现代的高性能web框架，它结合了Python类型注解和自动生成OpenAPI文档的功能。Swagger是一种用于API文档编写和生成的规范，可以帮助我们在开发API时更加高效和规范。

安装

在开始之前，我们需要安装FastAPI和相关的依赖。可以使用以下命令来安装：

pip install fastapi uvicorn

创建第一个FastAPI应用

让我们来创建一个简单的FastAPI应用，创建一个名为main.py的文件，然后编写以下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World"}

现在我们可以使用Uvicorn来运行这个应用：

uvicorn main:app --reload

在浏览器中访问http://127.0.0.1:8000，你将看到返回的JSON数据{"message": "Hello, World"}。

添加Swagger文档

FastAPI通过集成Swagger UI来自动生成API文档。只需在浏览器中访问http://127.0.0.1:8000/docs即可查看自动生成的API文档。

接着，我们可以继续优化我们的API，并添加更多的路由和参数。例如，我们添加一个接受参数的路由：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

这段代码中，我们定义了一个接受item_id和q参数的路由。接着，我们可以在Swagger文档中看到这个API并尝试调用。

参数校验和类型约束

FastAPI通过类型注解来实现参数校验和类型约束。这意味着我们可以很容易地定义参数的类型，并且FastAPI会根据这些信息来自动生成文档和进行参数校验。例如，我们定义一个接受name参数的路由：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

@app.get("/user/{name}")
def read_user(name: str):
    return {"name": name}

在这个示例中，我们定义了一个接受name参数的路由，并指定了参数的类型为str。如果我们尝试传入一个非字符串的参数，FastAPI会返回400错误。另外，Swagger文档也会根据这个信息来生成相应的参数说明。

返回数据模型

除了定义参数类型，我们还可以定义返回数据的模型。这样可以让我们更清晰地了解API的返回数据结构。例如，我们定义一个返回数据模型Item：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

接着，我们修改之前的路由，返回一个Item实例：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

@app.get("/")
def read_root():
    return {"message": "Hello, World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

@app.get("/user/{name}")
def read_user(name: str):
    return {"name": name}

@app.post("/items/")
def create_item(item: Item):
    return item

在这个示例中，我们定义了一个返回数据模型Item，并在一个新的路由/items/中返回一个Item实例。在Swagger文档中，我们可以看到这个API的返回数据结构。

API分组和版本控制

在大型的项目中，API通常会被分组和版本控制。FastAPI提供了方便的方式来实现API的分组和版本控制。例如，我们分组/items相关的API，并实现版本控制：

from fastapi import FastAPI, APIRouter

app = FastAPI()

v1_router = APIRouter()
v2_router = APIRouter()

@v1_router.get("/items/")
def get_items_v1():
    return {"version": "v1", "items": ["item1", "item2"]}

@v2_router.get("/items/")
def get_items_v2():
    return {"version": "v2", "items": ["item3", "item4"]}

app.include_router(v1_router, prefix="/v1")
app.include_router(v2_router, prefix="/v2")

在这个示例中，我们定义了两个不同版本的/items/路由，并通过APIRouter来进行分组。接着，我们使用include_router方法将路由添加到FastAPI应用中。在Swagger文档中，我们可以看到不同版本的API并进行调用。

总结

通过本文的介绍，我们了解了如何使用FastAPI框架来快速开发API，并如何通过Swagger自动生成API文档。FastAPI结合了Python类型注解和自动生成OpenAPI文档的功能，使得API的开发更加高效和规范。在实际开发中，我们可以根据需求来定义参数校验和返回数据模型，同时也可以在大型项目中进行API分组和版本控制。