flasgger是flask生态中轻量且标准的swagger集成方案，支持docstring和外部yml双模式，生成openapi 2.0规范json；需注意路径、缩进、schema定义及调试方法。
Flask 项目里加 Swagger 文档，Flasgger 是最轻量靠谱的选择
不用重写路由、不侵入业务逻辑、支持 YML 和 Python 注释双模式——Flasgger 就是 Flask 生态里事实标准的 Swagger 集成方案。它底层用的是 bravado-core 做 schema 校验，生成的是符合 OpenAPI 2.0（Swagger 2.0）规范的 JSON，能直接被 Swagger UI 渲染。
常见误区是以为必须手写完整 YML 文件，其实大可不必：Flasgger 支持在视图函数上用 docstring 写 YML 片段，自动拼装；也支持单独挂载外部 swagger.yml，适合已有规范或多人协作场景。
用 @swag_from 加载外部 YML 文件，路径和 key 必须严格匹配
YML 文件不是随便放就能读的。@swag_from 默认按相对路径查找，但实际行为取决于 Flask 的 root_path（通常是 app.py 所在目录），不是当前文件所在目录。容易报错：FileNotFoundError: [Errno 2] No such file or directory: 'swagger.yml'。
- 把
swagger.yml放在app.root_path下（比如和app.py同级），然后用@swag_from('swagger.yml') - 如果放在子目录如
docs/swagger.yml，得写全路径：@swag_from('docs/swagger.yml') - YML 顶层必须有
paths，且 key 要和路由 path 完全一致（包括 trailing slash 是否存在）；例如路由是/api/users/，YML 里就得写/api/users/:，写成/api/users会失效 - YML 中的
responses不填schema字段，UI 上就只显示 status code，没返回结构预览
用 docstring 写 YML 片段更灵活，但缩进和空行很关键
在视图函数里写三引号 docstring，内容是合法 YML，Flasgger 会自动解析。比外置 YML 更易维护，尤其对小项目或快速迭代接口。
典型失败案例：YML 缩进错一位、response 下漏了 description、或者 docstring 开头多了一个空行——都会导致 yaml.scanner.ScannerError 或静默忽略文档。
- 必须顶格写
---开头（哪怕只有一段），否则不识别为 YAML -
parameters列表里每个 item 的name必须和request.args/request.json实际字段名一致；in: body时，schema要嵌套一层$ref: '#/definitions/User'或直接写 inline 字典 - 定义
definitions时，不能放在 docstring 里——它只作用于单个接口；跨接口复用模型，得走Flasgger.add_swagger_resource()或全局template - 字符串值里含冒号（如
default: "2023-01-01"）必须加引号，否则 YAML 解析失败
调试时打开 DEBUG 模式并检查 /apidocs/ 页面源码
本地跑起来后访问 /apidocs/ 看不到接口？别急着重装包。先确认 app.config['SWAGGER'] = {'title': 'My API'} 已设置，且 Flasgger(app) 在所有路由注册之后调用。
真正管用的排查动作是打开浏览器开发者工具，切到 Network 标签，刷新 /apidocs/，看是否成功加载了 /swagger.json。如果返回 404，说明 Flasgger 没挂载成功；如果返回 JSON 但字段为空，大概率是 docstring/YML 语法错误，此时看 Flask 控制台有没有 YAMLError 日志。
另一个隐蔽坑：flasgger 默认不校验请求体是否符合 schema，要开启验证得额外配 validate=True 并处理 ValidationError 异常，否则即使传错字段类型也不会报错。
YML 的缩进、引用、空值写法这些细节，在 Python 里不像 JSON 那样有明确报错位置，多试两次 yaml.load() 单独解析你的片段，比硬扛运行时错误快得多。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
