最省事方式是用flask-swagger-ui：先暴露/openapi.json路由返回合规OpenAPI JSON（含paths、components.schemas、info.title等必填字段），再用get_swaggerui_blueprint挂载UI；注意Nginx需代理.json请求、响应头设Content-Type: application/json，且Swagger UI发请求时需匹配后端接收类型。
Flask 项目里怎么加 Swagger UI 页面
直接用 flask-swagger-ui 最省事，它不改你的路由逻辑，也不要求你写 YAML；把生成的 OpenAPI JSON 接口挂上去就行。核心是两步：暴露一个返回 openapi.json 的路由 + 静态挂载 UI。
- 别装
flask-restx或apispec除非你 already 在用它们——它们自带 Swagger 集成，但强耦合了定义方式，容易让已有 Flask 路由“被迫重构” -
flask-swagger-ui的get_swaggerui_blueprint必须传url参数，指向你的 OpenAPI spec 地址（比如/static/openapi.json），不是文件路径 - OpenAPI JSON 不要硬编码生成——用
flask-swagger-gen或手写脚本从@app.route装饰器+docstring 提取，否则字段漏写、类型错位，UI 上点测试就 400
手动构造 OpenAPI JSON 时哪些字段不能少
Swagger UI 能渲染、能发请求，只依赖三个东西：paths、components.schemas、info.title。少任何一个，页面空白或报 Resolver error。
-
paths里每个方法必须有summary和responses，哪怕只写{"200": {"description": "OK"}}；没有responses就无法生成 “Try it out” 按钮 - 所有
requestBody中的schema必须在components.schemas里定义，且引用格式为{"$ref": "#/components/schemas/UserInput"}；写成内联{"type": "object"}会导致 UI 不显示参数输入框 - 路径参数（如
/users/<user_id></user_id>）要在paths["/users/{user_id}"]下声明parameters，且name必须和花括号里一致，大小写敏感
为什么本地能跑，部署到 Nginx 后 Swagger UI 找不到 openapi.json
根本不是跨域问题，而是 Nginx 默认不代理以 .json 结尾的静态请求——它直接返回 404，连 Flask 都没进。
- 检查 Nginx 配置里有没有
location ~ \.json$这类拦截规则，删掉或加上proxy_pass http://flask_app; - 确保 Flask 返回的
openapi.json响应头含Content-Type: application/json；用curl -I http://yoursite/static/openapi.json看，如果是text/plain，Swagger UI 会静默失败 - 不要把
openapi.json放在static/目录下靠 Flask 自动 serve——它可能被缓存、没设 MIME 类型；统一走一个视图函数返回，显式设content_type="application/json"
测试时 POST 请求总卡住或返回 415 Unsupported Media Type
Swagger UI 默认发 Content-Type: application/json，但你的 Flask 路由如果没声明 request.is_json 或没调 request.get_json()，就收不到 body；更常见的是，你写了 @app.route(..., methods=["POST"]) 却没处理 multipart/form-data 或 application/x-www-form-urlencoded。
立即学习“Python免费学习笔记（深入）”；
- 确认路由函数开头有
if not request.is_json:分支，或统一用request.get_json(force=True)（仅调试用，线上慎开force） - 如果接口实际接收表单数据，Swagger UI 的
consumes字段得写成["application/x-www-form-urlencoded"]，并在request.form里取值；否则 UI 仍发 JSON，后端解析失败 - Swagger UI 的 “Try it out” 对数组参数支持弱——传
tags=["a","b"]可能被转成字符串"[\"a\",\"b\"]"；建议在 schema 里用"type": "array", "items": {"type": "string"}并勾选 “allowEmptyValue”
OpenAPI spec 里每个字段的语义约束比看起来严格得多，少一个引号、多一个空格、路径参数名对不上，Swagger UI 就不给你发请求——它不报错，只是按钮变灰或者点下去没反应。
