极客教程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分组和版本控制。