swag init报“cannot find package”是因为它不读go.mod而直接解析import路径，需确保在模块根目录执行并用-g指定入口文件，如swag init -g cmd/api/main.go，多模块时加--parsedependency。
为什么直接用 swag init 会报错 “cannot find package”
因为 swag 工具本身不读取 go.mod 里的依赖，而是直接扫描源码中的 import 路径。如果你的 handler 或 model 分布在非主模块路径（比如子模块、内部包带 vendor、或用了 replace 指向本地路径），swag init 就会找不到类型定义，报类似 cannot find package "your-domain/internal/model" 的错误。
解决方法不是改代码结构，而是告诉 swag 哪里找：
- 确保当前工作目录是模块根目录（含
go.mod） - 加
-g参数指定 main 入口文件，例如：swag init -g cmd/api/main.go - 若用了 Go workspace 或多模块，加
--parseDependency强制解析依赖包（但会变慢） - 避免在注释里写未导出字段名（如
type User struct { name string }），swag会跳过它们，导致 schema 缺失
如何让 Swagger UI 正确显示 gin 路由的参数和响应结构
swag 不自动识别 gin 的 c.Param() 或 c.Query()，必须手动用注释声明。否则 UI 里参数栏空白，测试按钮点不动。
关键不是写对函数，而是写对位置和格式：
- 路由处理函数上方必须有
// @Summary，否则整个接口不被收录 - 路径参数用
// @Param id path string true "user ID"，注意path类型不能写成query - 请求体必须标注结构体名，且该结构体需有 JSON tag 和导出字段，例如：
// @Param req body model.UserCreateRequest true "user data" - 响应用
// @Success 200 {object} model.User，不能写*model.User或匿名 struct - 如果用了
gin.H或map[string]interface{}，Swagger 无法生成 schema，得换成具体 struct
为什么本地能跑 Swagger UI，部署到 Docker 后 404
常见原因是静态文件没打包进二进制或镜像里。swag init 生成的 docs/ 目录默认不在 Go 编译范围内，Docker 构建时若只 COPY 二进制，就丢了文档资源。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
两个可靠做法：
- 用
statik或packr2把docs/打包进二进制（推荐packr2：运行packr2 clean && packr2 build，然后代码里用packr.New().HTTPBox("docs")注册路由） - 或者在 Dockerfile 中显式 COPY
docs/到镜像内，并确保 Web 服务从该路径 serve 静态文件（例如 Gin 用r.Static("/swagger", "./docs")） - 别用相对路径如
./docs启动服务——容器里工作目录可能不是你预期的
如何避免 swag 重复生成导致 Git 冲突或 CI 失败
swag init 每次都会重写 docs/docs.go，哪怕内容没变，时间戳和 hash 也会不同，造成无意义 diff。
稳定做法只有两个：
- CI 中禁止自动生成：把
docs/提交进仓库，CI 只做校验（运行swag init -o docs --quiet+git diff --exit-code docs），不一致就失败 - 开发时统一命令：在
Makefile里固定为swag init -g cmd/api/main.go -o docs -q，所有人执行同一句，减少格式差异 - 别把
swag当成“一键同步工具”，它本质是代码即文档的快照，更新应伴随接口变更一起 Code Review
最常被忽略的一点：Swagger 注释里的类型名必须和实际编译后的符号完全一致——大小写、包路径、是否带版本后缀（如 v1.User ≠ model.User），差一个字符，UI 就渲染不出结构。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
