Swagger生成的JSON默认为OpenAPI 2.0格式，Postman导入后会丢失请求体示例等信息；需用openapi2postmanv2工具升级为OpenAPI 3.0+并转换为Postman集合，同时补全@Param、@Security等注释以确保参数、鉴权和路径正确识别。
Swagger 生成的 JSON 不符合 Postman 导入规范
Echo 框架本身不内置 Swagger 文档生成，需借助 swaggo/swag（即 swag init）生成 swagger.json。但 Postman 要求的是 OpenAPI 3.0+ 格式的集合（collection v2.1），而 swag init 默认输出的是 OpenAPI 2.0（Swagger 2.0）格式 —— Postman 虽能导入，但会丢失请求体示例、部分参数类型、安全方案等关键信息，且无法正确识别 multipart/form-data 或 application/json 的 schema 结构。
解决路径很明确：必须将 Echo 项目生成的 OpenAPI 2.0 JSON 升级为 OpenAPI 3.0+，再转成 Postman collection。推荐用开源工具 openapi2postmanv2（Node.js CLI），它支持 OpenAPI 2/3 双向转换，且对 Echo + swag 的常见注释（如 // @Param, // @Success）兼容良好。
- 确保
swag init -g ./main.go -o ./docs成功生成docs/swagger.json - 安装转换工具：
npm install -g openapi2postmanv2 - 执行升级与转换：
openapi2postmanv2 -s ./docs/swagger.json -o ./postman_collection.json --folder（--folder保留分组结构，对应 Echo 中的 Group 路由）
Echo 路由注释缺失导致 Postman 缺少请求体或参数
Postman 集合中「Body」和「Params」栏为空，大概率是 Echo handler 上的 Swagger 注释没写全。Swag 工具只扫描 Go 源码中的特定注释块，@Param 和 @Success 是基础，但 @Param 必须显式声明 in: body 或 in: formData，否则不会生成 Body Schema。
例如处理 JSON POST 请求：
立即学习“go语言免费学习笔记（深入）”；
// @Param input body models.User true "user info"
// @Success 200 {object} models.UserResponse
func createUser(c echo.Context) error {
// ...
}
注意点：
-
models.User必须是可导出结构体（首字母大写），且字段带json:tag，否则swag无法提取字段定义 - 若用
echo.FormFile()接收文件，需加// @Param file formData file true "upload file"，否则 Postman 不会出现 form-data tab - 路径参数（如
/users/:id）要写// @Param id path int true "user ID"，不然 Postman 的 URL 参数栏为空
Postman 导入后 Authorization 未自动配置
Echo 中常用 echo.JWTMiddleware 或自定义中间件校验 token，但 Swag 默认不生成安全方案（securitySchemes），导致 Postman 集合里所有接口的 Auth 类型都是「No Auth」。
需手动在 main.go 或 docs/docs.go 的全局注释中补全：
// @SecurityDefinitions.apikey ApiKeyAuth // @In header // @Name Authorization // @Description Bearer token // @SecurityDefinitions.apikey BearerAuth // @In header // @Name Authorization // @Description Bearer token
然后在每个需要鉴权的 handler 上加：
// @Security ApiKeyAuth // 或 // @Security BearerAuth
这样 swag init 才会在 swagger.json 的 components.securitySchemes 下生成对应定义，openapi2postmanv2 才能映射为 Postman 的「Bearer Token」或「API Key」模式。
导出集合后环境变量和测试脚本无法复用
Postman collection JSON 本身不含环境变量（如 {{base_url}}）或测试脚本（pm.test），这些必须靠 Postman 客户端手动添加或通过 newman + postman-collection-transformer 二次注入 —— 但没必要绕这么大弯。
更务实的做法是：把基础 URL 抽离成变量，在 Echo 的 Swagger 注释中用 @Host 和 @BasePath 声明，例如：
// @Host api.example.com // @BasePath /v1
这样生成的 swagger.json 里会有 host 和 basePath 字段，openapi2postmanv2 会自动转成 Postman 的 request.url.host 和 request.url.path 数组，后续可在 Postman UI 中统一替换为变量，无需硬编码。
真正该在代码侧做的，是把典型响应断言逻辑写进 Go test，而不是强求 Swagger 导出测试脚本 —— 后者维护成本高，且 Postman 的 JS 运行时和 Go 语义差异太大，容易误导。
