FastAPI教程-接口文档：Swagger‑UI、ReDoc 作者：马育民 • 2026-08-13 11:12 • 阅读：10001 # 介绍 FastAPI 自带两套开箱即用的接口文档：**Swagger‑UI（/docs）** 和 **ReDoc（/redoc）**，底层都读取同一个 `openapi.json` 接口元数据，只是展示界面、能力不一样。 # Swagger‑UI 日常开发调试最常用的文档 访问地址 `/docs` [](http://www.malaoshi.top/upload/0/0/1GW3qzaFk8qe.png) ### 特点 可交互式调试接口 1. 可视化展示全部接口，按标签分组展示，每个接口可以展开查看。 2. 支持在线调试：页面上直接填参数、请求体、请求头，直接发送 HTTP 请求访问后端服务，不需要 Postman、Apifox。 3. 可以配置授权：右上角 Authorize，填入 Token，后续所有接口请求自动带上鉴权头部。 4. 请求执行后，可以直接看到：实际curl命令、请求地址、状态码、返回数据、错误示例。 5. 会自动展示请求/响应的数据模型、字段说明、数据类型。 ### 适合场景 - 后端开发自测接口 - 前后端对接，前端直接在页面试接口 - 测试人员快速验证接口 ### 缺点 界面信息量大，接口很多的时候页面会显得拥挤。 --- # ReDoc（） 纯阅读型文档，**不能发送请求调试**。 访问地址 `/redoc` [](http://www.malaoshi.top/upload/0/0/1GW3qzbuIOZm.png) ### 特点 侧重阅读，排版整洁 1. 排版像正式产品说明书，侧边导航栏，适合查阅，界面干净清爽。 2. 完整展示接口说明、参数、返回模型、字段注释。 3. 支持折叠大的模型定义，适合查阅复杂数据结构。 4. **没有 Try it out 按钮，不能在线发起请求，不能填参数调试。** ### 适合场景 - 对外交付给合作方看的正式接口说明文档 - 查阅接口定义，不做调试操作 ### 小缺点 完全没有交互调试能力，只能看，不能调用接口。 --- # 底层共性 两者都基于 OpenAPI 规范，后端会生成一份原始 JSON 文件 `/openapi.json`。 这个JSON可以导出，导入 Apifox、Postman 等工具生成接口集合。 # 对比 |项目|Swagger‑UI(/docs)|ReDoc(/redoc)| |---|---|---| |能否在线调用接口|✅可以调试请求|❌仅阅读| |授权登录|支持|不支持| |界面风格|交互工具风|书籍文档风| |主要用途|开发调试、自测|查阅、对外文档交付| ### 使用选择 - 开发阶段优先打开 `/docs` - 如果要给别人看正式文档，可以提供 `/redoc`；生产环境建议两者都关闭。 原文出处：/show_1GW3qzcFdQYn.html