FastAPI自动交互文档：Swagger UI与ReDoc使用教程

本节目标：访问 FastAPI 自动生成的两套在线文档，学会在网页里直接发请求调试接口，并理解它们是如何从代码自动产生的。

5-1 自动文档为什么是杀手锏

写接口最烦的一件事，是维护文档。代码改了，文档忘了改，前后端就吵起来。

FastAPI 从设计上解决了这个痛点：你每写一个接口，文档就自动生成，而且永远和代码一致。

它靠的是你在代码里写的类型提示和函数定义。这些信息本来就要写，FastAPI 顺手把它们整理成了标准格式的文档。

不用装插件，不用写额外配置，启动服务就有。这就是”自动交互文档”的含义。

Tip

所谓”交互式”，是指文档页面本身就能发请求、看响应，不只是干巴巴地看说明。

5-2 第一套文档：Swagger UI 的 /docs

先确保服务在跑（执行 fastapi dev main.py）。然后浏览器打开：

http://127.0.0.1:8000/docs

你会看到一个标题为 “FastAPI” 的页面，里面列着你的接口 /。这就是 Swagger UI，由 FastAPI 默认内置。

它不只是展示，还能直接操作。点开接口卡片，能看到请求方式、参数说明，非常适合边看边试。

Note

用 fastapi dev 启动时，控制台日志里那行 “Documentation at http://127.0.0.1:8000/docs” 指的就是它。

5-3 在 Swagger UI 里调试请求

Swagger UI 的调试分几步，跟着点就行：

第一步，点开 / 接口的卡片，展开详情。

第二步，点右上角的 “Try it out” 按钮，参数框会变成可编辑状态。

第三步，填写需要的参数（我们的 Hello World 没有参数，可跳过）。

第四步，点 “Execute” 按钮，页面会真的向你的服务发一次请求。

第五步，向下看 “Responses” 区域，能看到状态码、响应体和 CURL 命令。

这套流程等于把 Postman 之类的工具直接搬进了文档页，对新手极其友好。

Tip

在 Responses 里能看到 FastAPI 自动生成的 curl 命令，复制它就能在终端复现同一次调用，方便排查问题。

5-4 第二套文档：ReDoc 的 /redoc

除了 Swagger UI，FastAPI 还内置了另一套文档，地址是：

http://127.0.0.1:8000/redoc

这是 ReDoc 提供的界面，排版更偏”阅读型”。左侧是接口目录，右侧是详细说明，适合慢慢浏览整套 API 定义。

两套文档内容同源，只是展现风格不同。调试用 Swagger UI，查阅用 ReDoc，是很多团队的习惯。

Note

两个地址都依赖同一个底层描述文件，所以内容永远一致，不会出现”两份文档对不上”的情况。

5-5 OpenAPI：文档背后的统一标准

这两套界面不是凭空画的，它们都读同一份”接口说明书”，这份说明书遵循 OpenAPI 标准。

OpenAPI 是一种用来描述 API 的规范，相当于接口的”蓝图”。它规定怎么写路径、参数、响应格式。

FastAPI 会根据你的代码，自动生成这份蓝图，并放在：

http://127.0.0.1:8000/openapi.json

直接用浏览器打开它，能看到一段结构化 JSON，这就是机器可读的接口定义。

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

Tip

openapi.json 不只是给文档看。很多工具（前端代码生成器、Postman、各类测试平台）都能直接吃它，自动产出调用代码。

5-6 文档是如何从代码自动生成的

原理其实很直观。你写的代码里包含这些信息：

路径 / 来自装饰器 @app.get("/")；操作 GET 来自装饰器的方法；参数和类型来自函数的类型注解；返回结构来自你 return 的数据形状。

FastAPI 在启动时扫描这些定义，按 OpenAPI 规范组装成 openapi.json，再交给 Swagger UI 和 ReDoc 渲染成网页。

所以你”写接口”的同时，其实也在”写文档”。这才是自动文档的本质：一份定义，多处使用。

Note

正因为文档来自代码，“代码即文档”不再是口号，而是 FastAPI 的默认行为。

5-7 看一个更丰富的例子

为了让你直观感受文档如何反映代码，把 main.py 稍微丰富一点：

from fastapi import FastAPI

app = FastAPI()


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


@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

这里多了一个带路径参数 item_id 和可选查询参数 q 的接口。保存后刷新 /docs。

你会发现文档里自动出现了 /items/{item_id}，并标注 item_id 是整数、q 是可选字符串。类型提示直接变成了文档字段。

Tip

注意 item_id: int 让 FastAPI 自动做类型转换和校验；若传入非整数，文档对应的接口会返回清晰的报错。这一切文档都替你写好了。

5-8 文档与代码永远同步

这是自动文档最大的价值：你改代码，文档立刻跟着变，不需要手动维护。

比如你把参数 q 从可选改成必填，或新增一个 POST 接口，刷新 /docs 就能看到最新结构。

传统手工文档经常”代码改了、文档没动”，导致联调事故。FastAPI 从机制上消灭了这个问题。

对团队协作来说，前端同学直接看 /docs 就能知道该传什么参数，沟通成本大幅下降。

Note

你也可以给接口加 summary、description、tags 等参数，或写函数文档字符串 docstring，这些都会出现在文档里，让说明更完整。

5-9 小结

自动交互文档是 FastAPI 最让人省心的能力之一。回顾本章要点：

/docs 是 Swagger UI，可在网页里直接调试请求。
/redoc 是 ReDoc，更适合阅读和浏览。
两者都读同一份 OpenAPI 描述，内容永远一致。
这份描述来自你的代码，所以文档与代码天然同步。

到这里，你已经掌握了从环境、安装、第一个接口到自动文档的完整入门链路。后面更进阶的路由、参数、数据校验，都会延续这套”类型提示驱动”的思路，学起来会越来越顺。

自动交互文档：Swagger UI 与 ReDoc

5-1 自动文档为什么是杀手锏

5-2 第一套文档：Swagger UI 的 /docs

5-3 在 Swagger UI 里调试请求

5-4 第二套文档：ReDoc 的 /redoc

5-5 OpenAPI：文档背后的统一标准

5-6 文档是如何从代码自动生成的

5-7 看一个更丰富的例子

5-8 文档与代码永远同步

5-9 小结