FuAdmin API 参考完全指南：Django Ninja OpenAPI 自动文档与 /api/docs 使用详解

FuAdmin API 参考完全指南Django Ninja OpenAPI 自动文档与 /api/docs 使用详解【免费下载链接】fu-admin采用当前最流行的技术栈 Vben Vue Vue3 Python Django NinjaFast Api 和 Django的结合开发的后端管理系统项目地址: https://gitcode.com/gh_mirrors/fu/fu-adminFuAdmin 是基于Django NinjaFast API 风格 Django ORM 结合开发的开源后端管理系统最大亮点之一接口文档自动文档化无需手写一行 OpenAPI。本指南带你从 0 到 1 理解 FuAdmin 的 API 参考体系——如何访问/api/docs在线文档、接口如何自动注册、认证与统一响应是怎么运作的适合新手快速上手。为什么选择 Django Ninja自动文档的底层逻辑很多新手写 Django 后端都会遇到同样的烦恼接口写完了文档还要手动补。Django Ninja 的解法是你在写接口函数时声明好参数和返回类型Pydantic 风格它就能自动生成符合OpenAPI原 Swagger开放标准的接口文档。FuAdmin 界面中「系统管理 → 菜单管理」页面左侧菜单树与右侧接口配置均由后端 API 提供数据它相比传统 DRF 的优势在官方说明里写得很清楚特性说明 自动文档基于类型注解生成 OpenAPI 文档接口与文档永远同步⚡ 高性能Pydantic 校验 原生 Python 函数无需序列化器样板代码 Django 深度集成直接使用 Django ORM、中间件、权限体系️ 开放标准基于 OpenAPI / JSON Schema可对接 Postman、Apifox 等工具这些设计思路可以在项目说明 backend/README.md 中找到完整阐述。一分钟上手如何访问 /api/docs 自动文档这是新手最常问的问题文档在哪 答案启动后端后浏览器访问/api/docs即可。快速启动步骤克隆仓库git clone https://gitcode.com/gh_mirrors/fu/fu-admin进入后端目录backend执行pip3 install -r requirements.txt安装依赖数据库迁移python3 manage.py migrate初始化数据python3 manage.py init启动服务python3 manage.py runserver 0.0.0.0:8000浏览器访问http://localhost:8000/api/docs文档路径来自 URL 路由配置api实例挂载在/api/前缀下而 Ninja 的docs_url默认值就是/docs两者拼起来即为/api/docs。相关代码见 backend/fuadmin/urls.py。在/api/docs页面里你可以浏览所有接口按 Tag 分组Demo / System / Generator每个接口的路径、方法、参数、返回结构一目了然Authorize 登录点击 Authorize 按钮粘贴 JWT Token即可在线调试需要鉴权的接口▶️Try it out直接在浏览器里发起真实请求查看返回结果无需另开 Postman下载 OpenAPI JSON页面右上角可导出完整 OpenAPI 规范导入 Apifox / Postman 团队共享API 入口是怎么组装的FuNinjaAPI 与路由注册FuAdmin 的 API 并非零散散落的视图函数而是集中在一个统一入口组装。打开 backend/fuadmin/api.py核心只有几行FuNinjaAPI(authGlobalAuth())创建 API 实例并注入全局认证api.add_router(/system/, system_router)把各模块路由挂到统一前缀api.exception_handler全局异常兜底统一转成标准错误格式三个业务模块的分工前缀模块作用/api/system/系统管理用户、角色、菜单、部门、字典、日志等核心接口/api/demo/演示模块标准 CRUD 样板新手照着抄即可/api/generator/代码生成自动生成前后端代码的元接口这种一个实例 多 Router的结构让/api/docs里的 Tag 分组天然清晰——这正是 backend/demo/router.py 里tags[Demo]的来源。怎么写一个自动出现在文档里的接口以 demo 模块为例一个完整的 CRUD 接口在 backend/demo/api.py 中只需要三步定义 SchemaDemoSchemaIn请求体、DemoSchemaOut响应体继承ModelSchema并声明model_fields字段校验和文档描述自动生成声明装饰器router.post(/demo, responseDemoSchemaOut)response参数直接决定了文档里的返回结构过滤参数Filters继承全局基类FuFilters列表查询的参数也会同步出现在文档中比如列表接口GET /api/demo/demo配合paginate(MyPagination)装饰器文档会自动展示page、pageSize两个分页参数——分页类 backend/utils/fu_ninja.py 同时定义了分页入参pageSize默认 10和出参itemstotal。 新手提示写接口时只要认真写类型注解文档质量就自动达标。想改接口描述加operation_description参数即可无需维护单独的文档文件。认证机制GlobalAuth 如何校验 JWT Token/api/docs里点击 Authorize 后填入的 Token走的正是全局认证器GlobalAuth。它的逻辑见 backend/utils/fu_auth.py解码 Token用SECRET_KEY校验 JWT 合法性并比对过期时间演示环境DEMOTrueGET 请求放行写操作一律拦截保护线上演示正式环境非超管用户需命中「菜单按钮权限」中配置的接口正则 方法否则返回 403「没有权限」白名单WHITE_LIST中的路径如登录接口免鉴权直接访问这套权限配置在管理后台「菜单管理」中可视化维护每个按钮权限对应一个后端接口地址和请求方法前端勾选、后端校验全链路闭环。统一响应格式所有接口长一个样FuAdmin 重写了 Ninja 的响应生成逻辑所有接口返回统一结构前端只需写一套解析逻辑{ code: 2000, result: { ...: 业务数据 }, message: success, success: true }✅成功code2000successtrue数据在result里❌异常全局异常处理器把未捕获异常转成code500或业务错误码 错误信息前端统一弹提示响应封装源码在 backend/utils/fu_ninja.py 的FuNinjaAPI.create_response方法中。对前端同学来说这意味着看任意一个接口的/api/docs示例响应就能推断其他所有接口的返回形状。前后端如何协作一个真实场景用户管理页面左侧部门树、右侧用户列表、新增/删除按钮背后分别对应/api/system/下不同接口的请求与响应假设你要给「用户管理」加一个重置密码功能标准流程是在/api/docs找到/api/system/user/set/repassword确认请求参数后端按 demo 样板新增接口写好 Schema —— 文档立刻自动更新在「菜单管理」中为该按钮配置权限标识见 backend/system/apis/button.py 对应的权限模型前端调用拿到result数据渲染页面全程没有手工维护任何文档这就是 OpenAPI 自动化的价值接口即文档文档即契约。常见问题 FAQQ1/api/docs 页面打不开先确认后端已启动默认 8000 端口再检查 URL 前缀。项目文档中给出的标准地址是http://localhost:8080/api/docs8080 为前端代理后端口直连后端则为http://localhost:8000/api/docs。Q2调用接口一直返回 401 / 403401 是 Token 缺失或过期默认有效期 12 小时见 backend/fuadmin/settings.py 的TOKEN_LIFETIME403 是没权限——让管理员在菜单管理中给你的角色勾选对应接口权限。Q3生产环境应该开放 /api/docs 吗建议在生产环境通过 Nginx 屏蔽该路径或设置docs_urlNone关闭文档页避免接口结构泄露给攻击者。Q4想把文档导出给团队用/api/docs页面右上角可下载 OpenAPI JSON 文件规范定义在 Ninja 的schema_url对应地址导入 Apifox、Postman、YApi 均可。写在最后FuAdmin 把Django Ninja 的 OpenAPI 自动文档能力落地成了一套完整的工作流统一入口组装、模块 Router 分组、Schema 类型注解、全局 JWT 认证、统一响应封装——你只需要专注写业务函数/api/docs会自动成为团队最可靠的接口参考手册。 上手建议先通读 demo 模块的 CRUD 样板backend/demo/api.py再对照/api/docs页面观察文档变化半小时即可掌握这套 API 参考体系的开发范式。【免费下载链接】fu-admin采用当前最流行的技术栈 Vben Vue Vue3 Python Django NinjaFast Api 和 Django的结合开发的后端管理系统项目地址: https://gitcode.com/gh_mirrors/fu/fu-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考