用途：为 Go Gin 项目生成并展示 Swagger/OpenAPI 文档，覆盖 CRUD 与认证端点的注解编写、模型说明、Swagger UI 设置以及从 Go 注解生成文档的流程。
主要能力：在 main() 前配置全局注解（标题、版本、host、BasePath、schemes、BearerAuth 安全定义）；为每个 handler 添加 @Summary、@Param、@Success、@Failure、@Router（用 {id} 而非 :id）等注解；用结构体标签 example、format、enums、swaggerignore、swaggertype、minimum/maximum、minLength/maxLength、default 生成示例与约束；挂载 Swagger UI 并支持 URL、DocExpansion、PersistAuthorization 等选项；运行时通过 docs.SwaggerInfo 动态覆盖 host/schemes/BasePath；用 build tags 在生产构建中剔除 Swagger。
必要用法：安装 CLI 与依赖：go install github.com/swaggo/swag/cmd/swag@latest；go get -u github.com/swaggo/gin-swagger；go get -u github.com/swaggo/files。确保 $(go env GOPATH)/bin 在 $PATH。空白导入 _ "myapp/docs" 注册生成的规范。生成命令示例：swag init -g cmd/api/main.go -d ./,./internal/handler,./internal/domain；swag fmt && swag init -g cmd/api/main.go；swag init -g cmd/api/main.go --parseInternal。输出 docs/docs.go、docs/swagger.json、docs/swagger.yaml。可在 Makefile 中用 docs-check 目标通过 git diff --exit-code docs/ 检查文档是否最新。访问路径 http://localhost:8080/swagger/index.html。
适用场景：为 Gin API 添加交互式 API 文档、记录请求响应模式、记录 JWT Bearer 认证、在 CI 中校验文档时效。
限制：无 watch 模式，每次改动 handler 或模型后需重跑 swag init；响应类型须用命名结构体，不能使用 gin.H 或 map[string]interface{}；存在 --parseInternal 导致模型名 internal_ 前缀、time.Time 渲染为对象等已知问题，需用 --useStructName 或 swaggertype 处理。官方文档与参考文件包含更多注解、文件上传、多认证方案及 CI 细节。