swagger 可自动生成 go 微服务实时文档，但需确保注释位置正确、结构体含 json tag、用 go-swagger 验证规范，并将文档生成与 api 测试集成进 ci，防止文档与代码脱节。
用 Swagger 生成 Go 微服务的实时文档
Go 服务跑起来后，文档却还是手写的？别硬扛。Swagger（OpenAPI）支持自动生成，但关键不是“能生成”，而是“不和代码脱节”。swag init 是入口，但它只认 // @title、// @description 这类注释，且必须放在 main.go 或包级注释里——放错位置就扫不到。
常见错误是把 API 注释写在 handler 函数内部，或者用了 // @Param 却漏了 @Success，结果生成的 JSON 缺字段、UI 显示 404。实际操作时注意三点：
-
swag init必须在包含main()的目录下执行，否则找不到入口包 - 每个 HTTP handler 上方必须有完整注释块，含
@Summary、@Tags、@Param（即使无参数也要写@Param body body string false "none"避免报错） - struct 字段要加
json:tag，否则@Success 200 {object} MyResp会显示空对象
用 go-swagger 验证 OpenAPI 规范是否合法
生成的 docs/swagger.json 不一定符合 OpenAPI 3.0 标准，尤其当用了自定义 schema 或嵌套 map 时，前端 Swagger UI 可能白屏。直接打开 UI 看不到接口，大概率是 JSON 本身不合规。
别靠肉眼检查，用 swagger validate docs/swagger.json 命令验证。它会报出具体行号和错误类型，比如 schema validation failed: object has no key "required" —— 这通常是因为 struct 字段没加 json: tag，导致生成的 schema 缺 required 字段。
更隐蔽的问题是：不同版本 go-swagger 对 omitempty 处理不一致。v0.30+ 默认把 omitempty 字段标为可选，而老版本可能忽略。若测试环境用旧版生成、生产用新版校验，就会失败。
用 httptest + testify 写轻量 API 测试，绕过网络开销
微服务一多，用 curl 或 Postman 跑回归测试太慢，还依赖服务已启动。Go 原生 httptest 可直接调用 handler，零网络、秒级执行，但容易写成“假测试”——比如只测状态码，不校验响应体结构或字段值。
真实测试要覆盖三件事：
- 用
httptest.NewServer启一个临时服务，或更推荐httptest.NewRecorder直接喂 request 给 handler 函数 - 响应体必须用
json.Unmarshal解析后再断言，不能只比对字符串（浮点数精度、字段顺序、空格都会导致误判） - 测试前手动构造好依赖（如 mock DB 接口），避免测试因数据库连不上而随机失败；
testify/mock可以，但简单场景用闭包函数替换依赖更轻量
把文档和测试集成进 CI，防止上线前才发现接口不一致
CI 里只跑单元测试不够。Swagger 文档和 API 行为必须同步，否则前端按文档联调，后端悄悄改了字段名，线上就炸。
两个关键检查点要加进 .github/workflows/ci.yml 或 Makefile：
- 每次 PR 提交，运行
swag init -g cmd/myapp/main.go，再 diff 新旧docs/swagger.json，有变更就提醒人工确认 - 新增或修改接口后，对应测试用例必须存在；可用
grep -r "@Router" ./internal/handler/ | wc -l统计路由数，再和go test -run=TestAPI | wc -l比对，差值非零就失败 - 禁止直接提交
docs/目录——它应由 CI 自动生成并推送到 gh-pages 分支，避免人为编辑引入偏差
最常被跳过的环节是：Swagger 注释更新了，但 handler 实际返回结构没改，导致文档和代码行为不一致。这种问题不会报错，只能靠测试用例反向卡住。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
