swag是go生态唯一稳定落地的api文档自动生成方案，通过静态解析源码注释生成openapi 3.0文档；需正确配置扫描路径（-d）、入口文件（-g）、package声明、@model结构体注释、基础类型参数及utf-8编码等硬性条件。
swag 是当前 Go 生态中唯一能稳定落地的 API 文档自动生成方案，其他工具或处于实验阶段，或无法覆盖真实项目结构。它不依赖运行时反射，而是静态解析源码注释，生成标准 OpenAPI 3.0 文档——这意味着你改一行注释，swag init 之后文档就同步更新，没有延迟、不需重启服务。
swag init 扫不到接口？检查扫描路径和入口文件
执行 swag init 后 docs/swagger.json 中 paths 为空，或 Swagger UI 显示首页但无接口列表，问题几乎总出在“没扫到 handler 文件”。
-
swag init默认只扫描当前目录及子目录下属于同一 module 的.go文件；若 handler 分散在internal/handler、pkg/api等路径，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go，否则可能漏掉跨包注册的路由逻辑 - 被扫描的文件不能是
package main（除非它真包含r.GET()这类注册），推荐把路由逻辑单独放在package router或package api - 所有 handler 文件必须有合法
package xxx声明，且不能含语法错误，否则整个文件被跳过
@Param 和 @Success 写错类型？swag 不认 Go 类型系统
报错类似 cannot find type definition for "uuid.UUID" 或 unknown type "string"，本质是 swag 的类型解析器与 Go 编译器不一致：它只识别基础类型名和已用 // @Model 显式声明过的 struct。
-
@Param id path string true "用户ID"✅ —— 路径/查询/请求头参数只能用string、int、bool、float64，别写int64或uuid.UUID -
@Param user body model.User true "用户信息"✅ —— 请求体（in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse✅ —— 结构体必须导出（首字母大写），字段必须带json:tag，否则字段不会出现在 schema 中 - 数组参数写法：
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不能简写为type: []string
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，大概率不是配置问题，而是代码层面没满足 swag 的硬性要求。
- 源文件编码必须是 UTF-8（用
file -i handler.go检查），VS Code 右下角可确认编码格式 - 所有用于请求/响应的结构体字段必须导出（首字母大写），且每个字段必须有
json:tag，例如Name string `json:"name"` - 若结构体在另一个 module（如
github.com/yourname/project/models），需在main.go或全局注释处加// @modelsPackage github.com/yourname/project/models
集成 Swagger UI 到 Gin/Echo 服务时，静态资源挂载容易漏掉关键细节
生成 docs/ 目录后，不手动挂载，访问 /swagger/index.html 就会 404。这步不是可选项，而是必做动作。
- Gin 用户：导入
github.com/swaggo/gin-swagger和github.com/swaggo/files，然后加一行r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - Echo 用户：用
github.com/swaggo/echo-swagger，调用e.GET("/swagger/*", echoSwagger.WrapHandler) - net/http 用户：用
http.FileServer挂载，但注意路径映射——http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs")))) - Docker 构建镜像时，必须显式
COPY docs/ docs/，否则容器内无静态资源
最常被忽略的是结构体字段的 json: tag 和跨 module 引用时的 // @modelsPackage 声明——这两点一错，文档里就只剩空 schema 和 “object” 字样，排查时容易绕远路。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
