Flask-RESTX 默认不启用 Swagger UI，需显式设置 doc='/' 才能访问 /swagger.json 和 UI；生产环境应设 doc=False；蓝本中需在注册时统一配置；reqparse 仅校验 query/form，JSON 校验须用 model + @api.expect()；405 错误源于未声明 HTTP 方法；嵌套模型必须为 api.model() 实例，attribute 指对象属性名。
Flask-RESTX 初始化时为什么没看到 Swagger 页面？
默认不启用 UI，得显式开启 doc 参数。很多人跑完示例只返回 JSON，以为框架坏了，其实是 Swagger 根本没加载。
- 初始化
Api时必须传doc='/'（或自定义路径），否则/swagger.json和 UI 都 404 - 开发环境建议用
doc='/'；生产环境务必设为doc=False，避免暴露接口细节 - 如果用了蓝本（Blueprint），
doc要在注册蓝本时统一配，不能只在Api构造时设
怎么给 endpoint 加参数校验又不手写 request.args？
用 reqparse 是 Flask-RESTX 最容易误用的模块——它只校验 query string 和 form data，不处理 JSON body，这点和 FastAPI 的 Pydantic 概念完全不同。
-
RequestParser对应GET查询参数或POST表单，不是 JSON：用parser.add_argument('name', type=str, required=True) - JSON body 校验得靠
model+@api.expect()，比如定义user_model后加@api.expect(user_model) - 混合场景（如 query + JSON）要分开写：一个
parser处理 URL 参数，一个model描述 body 结构
Swagger UI 显示 405 Method Not Allowed 怎么办？
这不是 Swagger 的错，是路由注册顺序或 HTTP 方法声明不匹配导致的。Flask-RESTX 默认只响应你明确声明的 method，没写的就直接拒掉。
- 检查
@api.route()下的@api.doc()是否漏写了methods=['POST']，或者 handler 函数没加对应装饰器（如@api.response(201, 'Created')不影响方法允许列表） - 如果用了
@api.hide或@api.deprecated，它们不会禁用 endpoint，但可能让人误以为接口还活着 - 调试时 curl 直接打
OPTIONS看响应头里的Allow字段，比看 Swagger 更准
模型嵌套和字段重命名为什么总报错？
fields.Nested 和 fields.String(attribute=...) 是高频出错点，核心在于：attribute 值是对象属性名，不是字典 key 名，且嵌套模型必须是 Model 实例，不能是 dict 或 class。
- 嵌套写法：
user_model = api.model('User', {'name': fields.String, 'profile': fields.Nested(profile_model)})，其中profile_model必须是另一个api.model()返回值 - 字段映射用
attribute，比如返回字段叫full_name但想显示为name，写fields.String(attribute='full_name') - 别用
fields.String(default=lambda: 'xxx')，lambda 在模型定义时就被执行一次，所有实例共享结果
Swagger 页面看着方便，但背后每个 api.model、每个 @api.expect、每个 doc 开关，都得和真实 handler 逻辑对齐。差一行参数声明，前端就收不到正确 schema，后端也拦不住脏数据。
