swag本身不负责JSON格式化展示，只生成紧凑格式的swagger.json和swagger.yaml；其单行设计源于使用json.Marshal而非MarshalIndent，旨在减小体积、提升加载速度，且不支持命令行开启缩进；需借助jq等外部工具手动美化，或确保@exemple注释提供合法JSON字符串以触发Swagger UI自动pretty-print。
swag 本身不负责 JSON 文档的“格式化展示”，它只生成 swagger.json（紧凑格式）和 swagger.yaml。你看到的带缩进、可读的 JSON 页面，是 Swagger UI 渲染时做的美化，不是 swag 输出的——这点容易搞混。
swag init 生成的 swagger.json 为什么是单行？
这是设计使然：swag init 调用的是 Go 的 json.Marshal（非 MarshalIndent），目的是减小文件体积、加快加载速度，尤其对大型 API 文档更关键。
- 它不支持通过命令行参数开启缩进输出；
--output只控制路径，不控制格式 - 即使你手动用
json.MarshalIndent重写docs/docs.go中的SwaggerJSON变量，下次swag init就会被覆盖 - 想保留缩进？只能在生成后用外部工具处理，比如：
jq '.' docs/swagger.json > docs/swagger.pretty.json
如何让 Swagger UI 展示时自动格式化 JSON 示例？
Swagger UI 默认会对请求/响应体中的 JSON 示例做 pretty-print，但前提是你的 @example 注释里给的是合法 JSON 字符串（不是 Go 字面量）。
Json Schema Toolkit
下载
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
- 错误写法：
@example json {Name: "foo", Age: 25}→ UI 会原样显示，不解析、不缩进 - 正确写法：
@example json {"name":"foo","age":25}→ UI 自动加缩进和语法高亮 - 注意双引号必须是英文、不能有尾随逗号、布尔值小写（
true，不是True） - 如果示例含换行或特殊字符，用
\n和\"转义，否则注释解析失败
自定义 JSON 响应结构体字段名时，swag 怎么映射？
swag 解析结构体字段靠的是 Go 的导出规则 + json: tag，但它**不执行运行时反射**，只做静态 AST 分析。
立即学习“go语言免费学习笔记（深入）”；
- 字段必须首字母大写（如
Name），否则 swag 完全忽略 -
json:"user_name"→ 文档中显示为user_name；json:"-"→ 字段不出现在文档中 -
json:",omitempty"不影响字段是否出现在 schema 中，只影响运行时序列化逻辑 - 嵌套结构体同理：每一层都得导出 + 有对应 tag，否则字段名回退到 Go 名（如
UserDetail→userDetail，取决于--propertyStrategy） - 别指望
json:"id,string"这类编码 hint 被 swag 识别——它只认字段名映射，不处理编解码行为
真正容易被忽略的是：swag 的注释解析器对 Go 语法非常敏感。一个多余的括号、少一个引号、或者用了未声明的类型别名，都会导致整个 handler 的文档丢失，且不报错——只能靠肉眼检查 swag init -v 的输出日志。
