如何在FastAPI中使用Swagger UI展示API文档

1. 简介

FastAPI是一种现代、快速（高性能）的Web框架，用于构建API。它是基于Python 3.6+类型提示功能的，支持异步请求和响应，并具有快速设计能力，以提高开发人员的开发速度。

Swagger UI是一种用于可视化和交互式文档的开源工具。它可以自动地为API生成和展示文档，使得API的开发人员和终端用户可以更方便地理解和操作API。本文将介绍如何在FastAPI中使用Swagger UI展示API文档，使API更加易于使用和理解。

2. 安装FastAPI和uvicorn

在开始之前，我们需要先安装FastAPI和uvicorn。FastAPI使用uvicorn作为HTTP服务器，uvicorn基于asyncio和Python 3.6+类型提示功能实现高性能。

可以使用pip安装FastAPI和uvicorn：

pip install fastapi uvicorn

3. 编写代码

接下来，我们可以开始编写FastAPI应用程序并展示API文档。首先，创建一个文件main.py并输入以下代码：

from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
    return {"message": "Hello World"}

这段代码定义了一个FastAPI应用程序，它具有一个名为“root”的路由，对应网站的根目录/。它返回一个JSON格式的响应，其中包含一条消息“Hello World”。

4. 运行应用程序并查看API文档

要运行FastAPI应用程序，请输入以下命令：

uvicorn main:app --reload

此命令将启动一个uvicorn服务器，并告诉它从名为main.py的文件中加载应用程序对象app。--reload参数指定服务器在代码更改时重新加载应用程序。

现在，我们可以在浏览器中访问http://localhost:8000/docs，看到自动生成的Swagger UI文档。Swagger UI的页面上将列出所有的路由和模型，以及有关它们的详细信息。

5. 定义路由和模型

现在，我们将添加一些路由和模型来定义API的功能和数据模型。

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None
@app.get("/")
async def root():
    return {"message": "Hello World"}
@app.post("/items/")
async def create_item(item: Item):
    return item
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

此代码模块添加了三个路由：

/：一个GET路由，返回一个JSON格式的响应，其中包含一条消息“Hello World”。

/items/：一个POST路由，它需要一个名为item的Item模型作为请求正文，并返回该模型作为响应正文。

/items/{item_id}：一个GET路由，它需要一个名为item_id的int参数，并可选的一个query参数q作为查询参数。它返回一个JSON格式的响应，其中包含一个名为item_id的参数和名为q的查询参数。

要查看路由的详细信息，请运行FastAPI应用程序并访问http://localhost:8000/docs。

6. 结论

本文介绍了如何在FastAPI中使用Swagger UI展示API文档，使得API更加易于使用和理解。我们还展示了如何定义路由和模型来定义API的功能和数据模型。通过使用FastAPI和Swagger UI，我们可以快速构建功能强大的API，并使它们易于理解和使用。