Flasgger需在Flask应用创建且所有蓝图注册完成后初始化，调用flasgger.init_app(app)；若提前初始化或蓝图未挂载，会导致swagger.json 404。
Flasgger 装了但 swagger.json 404？检查初始化顺序和蓝图注册
Flasgger 不是装完就自动生效的，它依赖 Flask 应用实例的生命周期。常见错误是把 Flasgger 实例创建得太早，比如在定义 app = Flask(__name__) 之前，或在蓝图未注册前就调用 swagger_ui 路由。
正确做法是：确保 Flasgger 初始化在 app 创建之后、所有路由（尤其是 @app.route 或 blueprint.add_url_rule）注册完成之后。
- 不要在
__init__.py中仅声明flasgger = Flasgger()就结束；必须调用flasgger.init_app(app) - 如果用了蓝图，确保蓝图已通过
app.register_blueprint()挂载，再初始化 Flasgger - 默认
/apidocs/和路由只在 <code>DEBUG=True且未显式禁用时才启用；生产环境需手动设config["SWAGGER"]["validate"] = True并确认config["SWAGGER"]["uiversion"]兼容
文档没渲染出参数或响应体？@swag_from 和 @swag.code 别混用
Flasgger 支持两种注释方式：装饰器式（@swag_from）和内联式（@swag.code + docstring）。两者底层处理逻辑不同，混用容易导致元数据丢失或覆盖。
推荐统一用 @swag_from 配合 YAML 文件，更可控也更易复用：
立即学习“Python免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
-
@swag_from("user_get.yml")：YAML 文件里写清楚parameters、responses、tags，路径用相对路径（从app.root_path开始算） - 避免在同一个视图函数上同时写
@swag.code(200)和@swag_from(...)，后者会覆盖前者 - YAML 中
in: query对应 URL 查询参数，in: path对应路由里的<id></id>，别写反；类型要用 OpenAPI v2 规范（如string、integer，不是 Python 的str或int）
POST 接口测试时报 415 Unsupported Media Type？检查 consumes 和请求头
Swagger UI 默认发 Content-Type: application/json，但如果接口实际接收的是 multipart/form-data 或 application/x-www-form-urlencoded，而 YAML 里没声明 consumes，就会触发 415 错误。
必须显式声明接口支持的内容类型：
- 在 YAML 的
consumes字段列出所有合法类型，例如：consumes: ["application/json", "application/x-www-form-urlencoded"] - 对应地，在
parameters中按类型组织字段：JSON 用in: body，表单用in: formData（注意：Flasgger 基于 Swagger 2.0，不支持 OpenAPI 3.0 的requestBody写法） - 如果用
in: formData，后端必须用request.form.get(...)取值，不能依赖request.get_json()
本地能跑，部署到 Gunicorn/Nginx 后 /apidocs/ 白屏？静态资源路径被截断
Flasgger 的 UI 依赖 swagger-ui-dist 提供的前端资源，默认走 Flask 的静态路由。但在反向代理环境下（如 Nginx），URL 前缀可能被改写，导致 /apidocs/swagger-ui-bundle.js 404。
关键不是改 Nginx 配置，而是让 Flasgger 知道真实访问路径：
- 启动时传入
config={"url_prefix": "/api"}（如果 API 文档挂载在/api/apidocs下） - 或设置
config["SWAGGER"]["specs_route"] = "/api/apidocs/"，并确保 Nginx 的location /api/正确透传给 Flask - 检查浏览器开发者工具 Network 标签页，确认
swagger.json是否返回 200 且内容是合法 JSON；如果是 HTML（比如 Nginx 默认 404 页面），说明路由根本没走到 Flask
Flasgger 的自动化程度有限，它不帮你处理反向代理的路径重写逻辑，这部分得靠你对部署拓扑的理解来补全。
