Go Web服务接入Swagger需用swag CLI静态解析注释生成OpenAPI文档，注释须紧贴handler函数、严格遵循格式，再通过HTTP暴露swagger.json并挂载UI。
Go Web服务接入 Swagger 文档，核心是生成符合 OpenAPI 3.0（或 Swagger 2.0）规范的 JSON/YAML，并提供一个前端 UI 渲染它。Golang 本身不内置支持，必须借助第三方工具链，且**不能只靠运行时反射自动推导全部接口语义**——字段描述、参数类型、响应示例等仍需显式标注。
用 swag CLI 生成 docs.go 和 swagger.json
swag 是目前最主流的 Go Swagger 工具，它通过解析源码注释生成 OpenAPI 文档。它不依赖运行时，而是静态扫描，因此必须确保：
-
swag init能正确识别所有含// @Summary等注释的 HTTP handler 函数 - 项目根目录下有
go.mod，且swag版本与 Go 模块兼容（推荐 v1.8+） - 注释必须紧贴函数定义上方，且每行以
// @开头，中间不能有空行
package main
import "github.com/gin-gonic/gin"
// @Summary 获取用户信息
// @Description 根据 user_id 返回用户详情
// @Tags users
// @Accept json
// @Produce json
// @Param user_id path int true "用户ID"
// @Success 200 {object} UserResponse
// @Router /users/{user_id} [get]
func getUser(c *gin.Context) {
// 实现逻辑
}
执行：swag init -g main.go -o ./docs，会生成 docs/docs.go 和 docs/swagger.json。注意：-g 指定入口文件，-o 指定输出目录，路径错误会导致找不到 handler。
在 Gin/Echo/HTTP server 中挂载 Swagger UI
生成文档后，需把 swagger.json 暴露为 HTTP 接口，并引入 Swagger UI 前端资源。以 Gin 为例，不建议直接用 gin-swagger 的旧版（依赖 Swagger 2.0），应使用适配 OpenAPI 3.0 的方式：
立即学习“go语言免费学习笔记（深入）”；
- 用
http.FileServer挂载docs/swagger.json到/swagger/doc.json - 用
gin.StaticFS或嵌入swag提供的 UI 文件（需go:embed或提前下载） - 避免硬编码路径：用
docs.SwaggerInfo.Host控制请求 base URL，否则 UI 请求/swagger/doc.json会 404
package main
import (
"net/http"
"github.com/gin-gonic/gin"
_ "your-project/docs" // 这行必须导入，触发 docs.init()
)
func main() {
r := gin.Default()
// 暴露 swagger.json
r.GET("/swagger/doc.json", func(c *gin.Context) {
c.Header("Content-Type", "application/json")
c.File("./docs/swagger.json")
})
// 挂载 Swagger UI（简化版，生产环境建议用独立 Nginx 或 embed）
r.StaticFS("/swagger", http.Dir("./docs")) // 需确保 ./docs 下有 index.html 等 UI 文件
r.Run(":8080")
}
若用 swag init 时加了 --parseVendor --parseInternal，还要确认 vendor/internal 包里的 handler 是否被扫描到——默认不扫，容易漏接口。
@Param 和 @Success 注释写法易错点
Swagger 注释不是自由文本，字段名、结构、大小写都严格匹配。常见翻车点：
-
@Param name的name必须和路由路径中一致：/users/{id}→@Param id path string true "ID"，写成user_id就不会出现在 UI 参数栏 -
@Success 200 {object} User要求User类型已用// @Model注释过，或位于可导出包中；匿名 struct 不会被识别 -
@Failure如果没写，默认 UI 不显示错误响应结构，但实际返回 400/500 时前端无法预期格式 - 数组类型必须写全：
{array} User，不能写[]User或User[]
嵌套结构体字段若未导出（小写首字母），即使有 // @description 也不会出现在生成的 schema 中——这是 Go 反射限制，不是 swag bug。
CI/CD 中自动生成文档并校验
把 swag init 加进 CI 流程，能防止代码合并后文档过期。关键动作：
- 每次 PR 构建时运行
swag init -o ./docs && git diff --quiet ./docs/swagger.json || (echo "swagger.json out of date"; exit 1) - 用
swagger-cli validate ./docs/swagger.json检查语法合法性（需全局安装swagger-cli） - 避免在
main.go里写大量 Swagger 注释——拆到各 handler 所在文件，用swag init -d ./internal/handler指定多目录
真正麻烦的不是生成，而是当接口改了但忘记更新 @Param 或 @Success 注释时，文档就和实际行为不一致。这种不一致不会报错，只会悄悄误导前端和测试人员。
