入门¶

最简单的 FastAPI 文件可以看起来像这样

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

将该代码复制到名为 main.py 的文件中。

运行实时服务器

$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid">main.py</u>

  <span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting development server 🚀

             Searching for package file structure from directories
             with <font color="#3465A4">__init__.py</font> files
             Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>

   <span style="background-color:#007166"><font color="#D3D7CF"> module </font></span>  🐍 main.py

     <span style="background-color:#007166"><font color="#D3D7CF"> code </font></span>  Importing the FastAPI app object from the module with
             the following code:

             <u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>

      <span style="background-color:#007166"><font color="#D3D7CF"> app </font></span>  Using import string: <font color="#3465A4">main:app</font>

   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font>
   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000/docs</u></font>

      <span style="background-color:#007166"><font color="#D3D7CF"> tip </font></span>  Running in development mode, for production use:
             <b>fastapi run</b>

             Logs:

     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Will watch for changes in these directories:
             <b>[</b><font color="#4E9A06">&apos;/home/user/code/awesomeapp&apos;</font><b>]</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font> <b>(</b>Press CTRL+C
             to quit<b>)</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started reloader process <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> using WatchFiles
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started server process <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Waiting for application startup.
     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Application startup complete.

在输出中，有一行类似这样的内容：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

这一行显示了您的应用程序正在本地计算机上运行的 URL。

检查一下¶

在浏览器中打开 http://127.0.0.1:8000。

您将看到如下 JSON 响应：

{"message": "Hello World"}

交互式 API 文档¶

现在访问 http://127.0.0.1:8000/docs。

您将看到自动交互式 API 文档（由 Swagger UI 提供）

Swagger UI

备选 API 文档¶

现在，访问 http://127.0.0.1:8000/redoc。

您将看到备选的自动文档（由 ReDoc 提供）

ReDoc

OpenAPI¶

FastAPI 使用 OpenAPI 标准生成一个包含您所有 API 的 "schema"。

"Schema"¶

“Schema”是对某事物的定义或描述。不是实现它的代码，而只是一个抽象的描述。

API "schema"¶

在这种情况下，OpenAPI 是一个规定如何定义 API schema 的规范。

此 schema 定义包括您的 API 路径、它们可能接受的参数等。

数据 "schema"¶

“Schema”一词也可能指代某些数据的形状，例如 JSON 内容。

在这种情况下，它将指 JSON 属性、它们的**数据类型**等。

OpenAPI 和 JSON Schema¶

OpenAPI 为您的 API 定义了一个 API schema。该 schema 使用 JSON Schema（JSON 数据 schema 的标准）包含您的 API 发送和接收的数据的定义（或“schemas”）。

查看 `openapi.json`¶

如果您想了解原始 OpenAPI schema 的样子，FastAPI 会自动生成一个 JSON (schema) 来描述您所有的 API。

您可以在此处直接查看： http://127.0.0.1:8000/openapi.json。

它将显示一个 JSON，内容如下：

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {



...

OpenAPI 的用途¶

OpenAPI schema 是支持两个内置的交互式文档系统的基础。

还有数十种替代方案，都基于 OpenAPI。您可以轻松地将任何这些替代方案添加到您使用 FastAPI 构建的应用程序中。

您还可以使用它来自动生成代码，用于与您的 API 通信的客户端。例如，前端、移动或 IoT 应用程序。

部署您的应用（可选）¶

您可以选择将您的 FastAPI 应用部署到 FastAPI Cloud，如果您还没注册，请去加入等候名单。🚀

如果您已经拥有 FastAPI Cloud 帐户（我们已从等候名单中邀请了您 😉），您只需一个命令即可部署您的应用程序。

在部署之前，请确保您已登录

$ fastapi login

You are logged in to FastAPI Cloud 🚀

然后部署您的应用

$ fastapi deploy

Deploying to FastAPI Cloud...

✅ Deployment successful!

🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev

就是这样！现在你可以在那个 URL 访问你的应用了。✨

回顾，一步一步¶

第 1 步：导入 `FastAPI`¶

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

FastAPI 是一个 Python 类，它提供了您 API 的所有功能。

技术细节

FastAPI 是一个直接继承自 Starlette 的类。

您也可以将所有 Starlette 的功能与 FastAPI 一起使用。

第 2 步：创建一个 `FastAPI` "实例"¶

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

这里的 app 变量将是 FastAPI 类的“实例”。

这将是创建您所有 API 的主要交互点。

第 3 步：创建一个路径操作¶

路径¶

这里的“路径”指的是 URL 的最后一部分，从第一个 / 开始。

因此，在一个 URL 中，例如

https://example.com/items/foo

...路径将是

/items/foo

信息

“路径”通常也称为“端点”或“路由”。

在构建 API 时，“路径”是分离“关注点”和“资源”的主要方式。

操作¶

这里的“操作”指的是 HTTP 的“方法”之一。

其中之一：

POST
GET
PUT
DELETE

...以及更不常见的

OPTIONS
HEAD
PATCH
TRACE

在 HTTP 协议中，您可以使用这些“方法”中的一种（或多种）与每个路径进行通信。

在构建 API 时，您通常使用这些特定的 HTTP 方法来执行特定操作。

通常您会使用

POST：用于创建数据。
GET：用于读取数据。
PUT：用于更新数据。
DELETE：用于删除数据。

因此，在 OpenAPI 中，每个 HTTP 方法都被称为“操作”。

我们也将其称为“操作”。

定义一个路径操作装饰器¶

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

@app.get("/") 告诉 FastAPI，下面的函数负责处理发送到

路径 /
使用 get 操作

@decorator 信息

Python 中 @something 这种语法称为“装饰器”。

将其放在函数上方。就像一个漂亮的装饰帽（我猜这个词就是这么来的）。

“装饰器”会接收下面的函数并对其进行一些操作。

在我们的例子中，这个装饰器告诉 FastAPI 下面的函数对应于**路径** / 和**操作** get。

这就是“路径操作装饰器”。

您也可以使用其他操作

@app.post()
@app.put()
@app.delete()

以及更不常见的

@app.options()
@app.head()
@app.patch()
@app.trace()

提示

您可以自由地按照自己的意愿使用每个操作（HTTP 方法）。

FastAPI 不强制任何特定含义。

这里的信息是作为指导，而不是要求。

例如，在使用 GraphQL 时，您通常只使用 POST 操作来执行所有操作。

第 4 步：定义路径操作函数¶

这是我们的“路径操作函数”

路径：是 /。
操作：是 get。
函数：是“装饰器”下方的函数（@app.get("/") 下方）。

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

这是一个 Python 函数。

当 FastAPI 收到对 URL “/” 使用 GET 操作的请求时，它会调用它。

在这种情况下，它是一个 async 函数。

您也可以将其定义为普通函数而不是 async def

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

注意

如果您不知道区别，请查看 Async：“急就章？”。

第 5 步：返回内容¶

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

您可以返回 dict、list、单个值，如 str、int 等。

您还可以返回 Pydantic 模型（稍后将详细介绍）。

有许多其他对象和模型将被自动转换为 JSON（包括 ORM 等）。尝试使用您最喜欢的，它们很可能已经受支持。

第 6 步：部署它¶

使用一个命令将您的应用部署到 FastAPI Cloud：fastapi deploy。🎉

关于 FastAPI Cloud¶

FastAPI Cloud 由 FastAPI 背后的同一作者和团队构建。

它以最小的努力简化了 API 的构建、部署和访问过程。

它将使用 FastAPI 构建应用的开发者体验带到了将它们部署到云端的过程中。🎉

FastAPI Cloud 是 FastAPI 及其相关开源项目的主要赞助商和资金提供者。✨

部署到其他云服务提供商¶

FastAPI 是开源的并且基于标准。你可以将 FastAPI 应用部署到你选择的任何云服务提供商。

遵循你的云服务提供商的指南来部署 FastAPI 应用。🤓

总结¶

导入 FastAPI。
创建一个 app 实例。
使用类似 @app.get("/") 的装饰器编写一个路径操作装饰器。
定义一个路径操作函数；例如，def root(): ...。
使用 fastapi dev 命令运行开发服务器。
可选地使用 fastapi deploy 部署您的应用。

入门¶

检查一下¶

交互式 API 文档¶

备选 API 文档¶

OpenAPI¶

"Schema"¶

API "schema"¶

数据 "schema"¶

OpenAPI 和 JSON Schema¶

查看 openapi.json¶

OpenAPI 的用途¶

部署您的应用（可选）¶

回顾，一步一步¶

第 1 步：导入 FastAPI¶

第 2 步：创建一个 FastAPI "实例"¶

第 3 步：创建一个路径操作¶

路径¶

操作¶

定义一个路径操作装饰器¶

第 4 步：定义路径操作函数¶

第 5 步：返回内容¶

第 6 步：部署它¶

关于 FastAPI Cloud¶

部署到其他云服务提供商¶

总结¶

查看 `openapi.json`¶

第 1 步：导入 `FastAPI`¶

第 2 步：创建一个 `FastAPI` "实例"¶