FastAPI 入门实战：从最小应用到自动文档、OpenAPI 与开发服务器全流程解析

2026-09-06 12:13:43作者：俞予舒Fleming

本文基于 FastAPI 官方文档的 "Erste Schritte"（入门）教程编写，完整覆盖"写一个最小 FastAPI 应用 → 启动开发服务器 → 查看自动生成的交互式 API 文档 → 理解 OpenAPI Schema → 配置应用入口 → 部署"的完整闭环，并结合仓库源码（fastapi/applications.py、fastapi/cli.py、pyproject.toml）剖析装饰器、实例与 CLI 命令背后的实现机制，适合刚接触 FastAPI 的开发者作为可复制、可验证的入门路线。

一、最简 FastAPI 应用

FastAPI 官方入门教程（docs/de/docs/tutorial/first-steps.md）给出的最小应用只有 8 行，位于 docs_src/first_steps/tutorial001_py310.py：

from fastapi import FastAPI

app = FastAPI()


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

把这 4 步理解清楚，就理解了 FastAPI 应用的全部骨架：

from fastapi import FastAPI —— 导入 FastAPI 类；
app = FastAPI() —— 创建一个应用实例，作为所有 API 的"主交互点"；
@app.get("/") —— 用"路径操作装饰器（Path Operation Decorator）"声明：下方函数负责处理对路径 / 的 GET 请求；
return {"message": "Hello World"} —— 返回的 Python 对象会被 FastAPI 自动转换为 JSON 响应。

把上面的代码保存为 main.py，即可作为后面所有步骤的起点。

/// 提示

FastAPI 提供了官方的 VS Code（以及 Cursor）编辑器扩展，提供路径操作 Explorer、路径操作搜索、从测试跳转到定义（CodeLens）、以及 Cloud 部署与日志查看等能力。该扩展与本文的 CLI 工作流互补，安装后可在编辑器内直接管理 FastAPI 应用。///

二、启动开发服务器：`fastapi dev`

在包含 main.py 的目录下执行：

$ uv run fastapi dev

（也可以使用 python -m fastapi dev 或先 pip install "fastapi[standard]" 后直接 fastapi dev。）

典型输出如下（省略部分着色标记）：

FastAPI  Starting development server 🚀

           Searching for package file structure from directories
           with __init__.py files
           Importing from /home/user/code/awesomeapp

  module  🐍 main.py

    code  Importing the FastAPI app object from the module with
           the following code:

           from main import app

     app  Using import string: main:app

  server  Server started at http://127.0.0.1:8000
  server  Documentation at http://127.0.0.1:8000/docs

     tip  Running in development mode, for production use:
          fastapi run

          Logs:

    INFO  Will watch for changes in these directories:
          ['/home/user/code/awesomeapp']
    INFO  Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
    INFO  Started reloader process [383138] using WatchFiles
    INFO  Started server process [383153]
    INFO  Waiting for application startup.
    INFO  Application startup complete.

其中需要关注的关键行：

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

这行输出给出了应用在本机对外提供服务的地址：http://127.0.0.1:8000。从输出可以看出几个要点：

自动发现应用：CLI 会搜索含 __init__.py 的包结构，定位到 main.py 模块；
导入约定：它按 from main import app（即 import string main:app）取出 FastAPI 应用对象，这一点与后文的 entrypoint 配置直接对应；
开发模式：fastapi dev 是开发服务器（带 WatchFiles 文件监听、改动即重载），生产环境应使用 fastapi run；
文档地址：启动信息里直接给出 http://127.0.0.1:8000/docs。

源码视角：`fastapi` 命令从哪来

仓库中的 pyproject.toml 在 [project.scripts] 段注册了命令入口：

[project.scripts]
fastapi = "fastapi.cli:main"

而 fastapi/cli.py 本身只是一个"转发器"——它尝试从独立包 fastapi_cli 导入 main，未安装时给出提示：

try:
    from fastapi_cli.cli import main as cli_main
except ImportError:  # pragma: no cover
    cli_main = None

def main() -> None:
    if not cli_main:
        message = 'To use the fastapi command, please install "fastapi[standard]":\n\n\tpip install "fastapi[standard]"\n'
        print(message)
        raise RuntimeError(message)
    cli_main()

也就是说，fastapi dev / fastapi run / fastapi deploy 等子命令的实际实现位于 fastapi-cli 包。这与 pyproject.toml 中 standard 可选依赖一致：

standard = [
    "fastapi-cli[standard] >=0.0.32",
    ...
    "uvicorn[standard] >=0.12.0",
    ...
]

所以前提条件是安装了带 standard 依赖组（含 fastapi-cli 与 uvicorn）的 FastAPI；仅 pip install fastapi 时运行 fastapi 命令会得到上面的安装提示。

三、测试与查看响应

3.1 浏览器访问根路径

打开浏览器访问 http://127.0.0.1:8000，会看到 JSON 响应（Response，即服务器返回给客户端的数据）：

{"message": "Hello World"}

3.2 交互式 API 文档（Swagger UI）

访问 http://127.0.0.1:8000/docs，可以看到自动生成的交互式 API 文档（由 Swagger UI 提供）。你可以在页面上直接填写参数、点击 "Try it out" 发起真实请求并查看响应——无需任何额外配置，文档随路由代码自动保持同步。

3.3 备选文档（ReDoc）

访问 http://127.0.0.1:8000/redoc，可以看到另一套自动生成的备选文档（由 ReDoc 提供）。ReDoc 以信息流式的只读方式组织文档，适合偏阅读、分发给只读用户的场景。两套文档共用同一份 OpenAPI 数据，因此内容完全一致，只是呈现形式不同。

四、OpenAPI 与自动生成的 `openapi.json`

FastAPI 使用 OpenAPI 标准自动生成描述整套 API 的 "Schema"（模式/模式定义）。这里需要对 "Schema" 一词做三层澄清（官方文档专门用四个小节解释）：

"Schema" 本义：指某样东西的定义或描述，是抽象描述而非实现代码本身；
API "Schema"：OpenAPI 是一份"规定如何定义 API 模式"的规范，FastAPI 生成的 API Schema 包含所有 API 路径、各路径可接收的参数等；
数据 "Schema"：同一术语也可指数据的"形状"，例如 JSON 内容中有哪些属性、每个属性的数据类型等。

OpenAPI 为整套 API 定义 API Schema，而其中对请求/响应数据的描述则使用 JSON Schema（JSON 数据模式标准）。

4.1 查看原始的 `openapi.json`

在 http://127.0.0.1:8000/openapi.json 可以直接看到 FastAPI 自动生成的原始 JSON，大致如下：

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

（以最小应用为例，paths 下会出现 "/": { "get": ... }，响应模型即 {"message": "Hello World"} 对应的 schema。）

4.2 OpenAPI Schema 有什么用

两套交互文档的共同基础：/docs 与 /redoc 都基于这份 Schema 渲染；
生态接入点：存在大量基于 OpenAPI 的第三方工具，可以无缝接入你的 FastAPI 应用；
客户端代码生成：可基于该 Schema 自动生成与 API 通信的客户端代码，例如前端、移动端或 IoT 应用。

五、在 `pyproject.toml` 中配置应用 `entrypoint`

对于多文件/多包结构的工程，可以在 pyproject.toml 中显式告诉 CLI 你的 App 在哪里：

[tool.fastapi]
entrypoint = "main:app"

这个 entrypoint 的语义是"按如下方式导入应用对象"：

from main import app

如果代码结构是包形式，例如：

.
├── backend
│   ├── main.py
│   ├── __init__.py

则应设置为：

[tool.fastapi]
entrypoint = "backend.main:app"

等价于：

from backend.main import app

5.1 用路径或 `--entrypoint` 选项替代配置

也可以不写 pyproject.toml，直接把文件路径传给 fastapi dev，CLI 会"猜"出要用的 FastAPI 应用对象：

$ uv run fastapi dev main.py

或者显式传递 --entrypoint 选项：

$ uv run fastapi dev --entrypoint main:app

但这样每次调用 fastapi 命令都要记得带上正确的路径/entrypoint，而且其他工具（如 VS Code 扩展、FastAPI Cloud）无法找到你的应用。因此官方推荐：将 entrypoint 写入 pyproject.toml，作为唯一事实来源。

5.2 `main:app` 约定与源码的对应关系

从前面 CLI 输出中的 Using import string: main:app 和 from main import app 可以看到，entrypoint 的格式就是 模块导入路径:变量名。这与测试代码的组织方式也一致：仓库的教程测试（如 tests/test_tutorial/test_first_steps/test_tutorial001_tutorial002_tutorial003.py）正是导入 docs_src/first_steps 下的 app 对象来验证行为——"模块 + 模块级 app 变量"是 FastAPI 生态中事实上的标准入口形态。

六、（可选）用一条命令部署到 FastAPI Cloud

官方提供了一条可选的部署路径：

$ uv run fastapi deploy

Deploying to FastAPI Cloud...

✅ Deployment successful!

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

fastapi deploy 会自动识别你的 FastAPI 应用并部署到 FastAPI Cloud（由 FastAPI 作者与团队开发，目标是把本地写 App 的开发者体验延续到云部署环节，并以云业务收入反哺 FastAPI and friends 开源项目）。若未登录，命令会打开浏览器完成认证。

如果不想用该云服务：FastAPI 是开源且基于标准的框架，你的应用同样可以部署到任意云厂商，按所选云厂商的 ASGI/容器部署指引操作即可。

七、逐步复盘：最小应用的每一步在做什么

以下复盘部分与原文档 "Zusammenfassung, Schritt für Schritt"（逐步总结）逐条对应，并结合源码给出实现依据。

步骤 1：导入 `FastAPI`

from fastapi import FastAPI

FastAPI 是一个 Python 类，提供了构建 API 所需的全部功能。

/// 技术细节：从源码看，fastapi/applications.py 中定义为 class FastAPI(Starlette)，即 FastAPI 直接继承自 Starlette，因此 Starlette 提供的全部底层能力（静态文件、中间件、路由原语等）在 FastAPI 中同样可用。///

步骤 2：创建 `FastAPI` "实例"

app = FastAPI()

变量 app 是 FastAPI 类的一个"实例（instance）"，是你创建整套 API 时的主交互对象：所有路由装饰器、中间件、异常处理器都挂在这个实例上。

步骤 3：创建"路径操作（Path Operation）"

路径（Path）：指 URL 中从第一个 / 开始的最后一段部分。例如 URL https://example.com/items/foo 中的路径是 /items/foo。"路径"也常被称作"端点（endpoint）"或"路由（route）"。在构建 API 时，路径是划分"关注点"与"资源"的最主要手段。

操作（Operation）：指 HTTP "方法"之一：

常用的：POST、GET、PUT、DELETE
较少用的：OPTIONS、HEAD、PATCH、TRACE

HTTP 协议允许对同一个路径通过一个或多个"方法"进行通信。构建 API 时通常用这些方法表达特定动作，约定俗成的对应关系是：

POST：创建数据（create）
GET：读取数据（read）
PUT：更新数据（update）
DELETE：删除数据（delete）

在 OpenAPI 中，每一种这样的 HTTP 方法都叫做"操作（operation）"，官方文档也称之为**"Operations"**。

定义路径操作装饰器：

@app.get("/")

@app.get("/") 告诉 FastAPI：它正下方的函数负责处理发往 路径 / 且使用 get 操作 的请求。

/// 关于 @decorator 语法：这种 @something 写法在 Python 中称为"装饰器（decorator）"，放在函数上方（名字据说就来自"装饰帽"的意象）。装饰器接收下方的函数并对其进行加工。在我们的场景中，这个装饰器把"下面的函数"与路径 / 和操作 get 关联起来，因此官方叫它"路径操作装饰器"。///

同理可以使用其他操作：@app.post()、@app.put()、@app.delete()，以及较少见的 @app.options()、@app.head()、@app.patch()、@app.trace()。

从源码看，这些方法都定义在 FastAPI 类上，例如 fastapi/applications.py 的 def get(self, path, *, response_model, ...)、put、post、delete 等方法（均为 APIRouter 同名方法的转发实现）。每个方法都接受大量参数，其中 response_model 用于指定响应类型——它决定了 OpenAPI 文档中展示的响应 JSON Schema，并用于把任意返回对象序列化为 JSON；此外还有 status_code、tags、summary、description、response_description 等文档/行为参数，这些正是 /docs 页面信息的直接来源。

/// 提示：你可以按自己的喜好使用任意操作（HTTP 方法），FastAPI 不强制某种语义。上述约定只是指南，不是硬性规定。例如使用 GraphQL 时，通常所有动作都通过 POST 操作完成。///

步骤 4：定义"路径操作函数"

这就是**"路径操作函数（Path Operation Function）"**，三要素对应：

路径：/
操作：get
函数：位于装饰器（@app.get("/")）正下方的函数

async def root():

它是一个 Python 函数，每当 FastAPI 收到对 URL / 的 GET 请求时就会被调用。此处定义的是 async 函数。

当然，也可以把它定义成普通（同步）函数，见 docs_src/first_steps/tutorial003_py310.py：

def root():
    return {"message": "Hello World"}

/// 提示：如果你还不清楚 async def 与普通 def 的区别，可参考官方文档的 Async: "In a hurry?" 小节。///

步骤 5：返回内容

return {"message": "Hello World"}

你可以返回 dict、list，以及 str、int 等标量值，也可以返回 Pydantic 模型。还有大量其他对象和模型（包括 ORM 对象等）都能被自动转换为 JSON——建议直接试试你常用库的对象，大概率已经支持。

步骤 6：部署

用 fastapi deploy 一条命令部署到 FastAPI Cloud；
或按所选云厂商的指引部署到任意云（FastAPI 基于标准、可移植）。

八、要点总结

按官方 "Zusammenfassung"（总结）一节，入门六步：

导入 FastAPI；
创建一个 app 实例（app = FastAPI()）；
使用 @app.get("/") 等装饰器书写路径操作装饰器；
定义路径操作函数，例如 def root(): ...；
用 fastapi dev 命令启动开发服务器；
（可选）用 fastapi deploy 部署你的应用。

延伸与验证路径

最小应用源码：docs_src/first_steps/tutorial001_py310.py（async 版）、docs_src/first_steps/tutorial003_py310.py（同步版）；
测试如何驱动这些教程代码：tests/test_tutorial/test_first_steps/；
fastapi 命令入口与 fastapi-cli 依赖关系：fastapi/cli.py、pyproject.toml（[project.scripts] 与 standard 依赖组）；
FastAPI 类及其 get/post/put/delete 等方法：fastapi/applications.py；
编辑器支持（VS Code 扩展）：docs/de/docs/editor-support.md；
异步细节：docs/de/docs/async.md。