如何在FastAPI中使用OpenAPI规范定义API接口-猿码集

1. 介绍

FastAPI是一个快速，现代化，Web框架，用于构建APIs和微服务。它基于Python 3.6+的标准类型提示进行构建，并使用非常快的代码生成以获得高性能。在这篇文章中，我们将了解如何使用FastAPI来定义API接口，并使用OpenAPI规范来描述它们。

2. 安装

2.1. 创建虚拟环境

首先，我们需要安装Python 3.6+。一旦安装了Python，我们可以使用虚拟环境来隔离我们的依赖项。打开终端并运行以下命令：

python3 -m venv env

source env/bin/activate

2.2. 安装FastAPI和uvicorn

安装FastAPI和uvicorn的最简单方法是使用pip。在终端中运行以下命令：

pip install fastapi uvicorn

3. 创建API

3.1. 创建main.py文件

在我们的项目目录中，我们将创建一个名为main.py的文件，该文件将包含我们的API定义。在main.py中，我们需要导入FastAPI：

from fastapi import FastAPI
app = FastAPI()

这将创建一个名为app的FastAPI实例，我们可以在其中定义路由，中间件等。

3.2. 添加路由

要添加路由，请使用app对实例进行装饰器。装饰器用于定义HTTP请求处理程序。我们将添加一个GET请求处理程序，该处理程序将返回“Hello World！”文本。我们可以这样做：

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

在这里，我们为根路径“/”添加了一个GET路由。路由的名称是“read_root”，我们使用async关键字定义它。对于此路由，我们简单地返回JSON对象：{"Hello": "World"}，FastAPI将自动将其转换为JSON格式并返回给客户端。

3.3. 运行应用程序

现在我们已经定义了我们的API，现在是时候运行它了。我们将使用uvicorn来运行它。在终端中，运行以下命令：

uvicorn main:app --reload

这将启动一个开发服务器，它将我们的应用程序绑定到http://localhost:8000。打开浏览器并转到此网址，您应该看到JSON响应：{"Hello": "World"}

4. 使用OpenAPI规范定义API接口

现在我们已经定义了一个简单的API，让我们看看如何使用OpenAPI规范来定义它。

4.1. 安装swagger-ui和pydantic

Swagger UI是一个可视化的用户界面，它为与API交互的用户提供了一个优雅的界面。我们将使用Swagger UI来显示我们的API规范。要安装Swagger UI，请使用以下命令：

pip install swagger-ui-pydantic

我们还需要安装pydantic，这是FastAPI使用的数据验证库：

pip install pydantic

4.2. 添加模型

我们需要为API模型定义一个数据模型。我们将使用pydantic的模型来定义此模型。在main.py文件中，添加以下代码：

from typing import Optional
from pydantic import BaseModel
class Item(BaseModel):
    name: str
    price: float
    is_offer: Optional[bool] = None

在这里，我们导入BaseModel和Optional类。我们定义了一个名为Item的数据模型，该模型有三个字段：名称，价格和是否为报价。我们使用价格和is_offer字段类型的float和Optional进行了注释。

4.3. 添加API路由

现在我们需要为我们的API路由添加一个数据模型。我们将使用HTTP POST请求来创建新项目。我们可以用以下代码来告诉FastAPI：

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

在这里，我们定义了一个名为create_item的POST路由，用于创建项目。我们使用了async和await关键字，以便我们可以异步地处理请求。我们还声明了一个名为item的参数，它使用我们在前面定义的Item数据模型。在此函数体内，我们仅返回了传递给我们的项目。

4.4. 添加Swagger UI支持

现在我们需要告诉FastAPI生成OpenAPI文档。为此，我们使用JSON对FastAPI进行OpenAPI描述注册。我们将使用一个FastAPI扩展程序来自动执行此操作。在main.py文件的顶部导入以下代码：

from fastapi.openapi.utils import get_openapi
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.staticfiles import StaticFiles
app = FastAPI(docs_url=None, redoc_url=None)
@app.get("/docs", include_in_schema=False)
async def get_documentation():
    return get_swagger_ui_html(openapi_url="/openapi.json", title="docs")
app.mount("/static", StaticFiles(directory="static"), name="static")
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="My API",
        version="0.1.0",
        description="This is a very good API",
        routes=app.routes,
    )
    app.openapi_schema = openapi_schema
    return app.openapi_schema
app.openapi = custom_openapi

在这里，我们定义了一个名为get_documentation的GET路由。该路由返回Swagger UI的HTML内容，其中包含对生成的API规范文件进行可视化的支持。

我们还添加了一个名为custom_openapi的函数，该函数返回我们的API规范定义。在这里，我们定义了API的名称，版本和描述。我们还将路由传递给get_openapi函数以生成API规范定义。

4.5. 运行应用程序

现在我们已经定义了我们的API规范，让我们运行它并查看在Swagger UI中如何显示它。运行以下命令启动服务器：

uvicorn main:app --reload

现在，我们可以打开http://localhost:8000/docs，看到Swagger UI，其中包含我们的API规范文档。它显示了转到/create_item路径的POST请求，该路径需要Item数据模型中定义的名称和价格字段。

总结

在本文中，我们学习了如何使用FastAPI定义API接口。我们还学习了如何使用OpenAPI规范来描述API，并使用Swagger UI自动生成文档。FastAPI是一个非常快速，现代化的Web框架，非常适合构建APIs和微服务。

如何在FastAPI中使用OpenAPI规范定义API接口