Go Swagger（Swaggo）是一个用于 Go 语言的开源工具集，它帮助开发者自动生成 API 文档。它利用 Go 的注释和结构体信息，通过解析代码，生成符合 OpenAPI 规范的文档。OpenAPI（也称为 Swagger）是一个广泛使用的 API 规范，它使得 API 文档更加标准化、易于理解和交互。
Swaggo 主要的功能包括：
Swaggo 通过解析 Go 文件中的注释，自动为项目中的 HTTP 路由生成符合 OpenAPI 规范的 API 文档。它能够生成描述 API 的所有细节，例如请求和响应参数、数据结构、返回状态码等。
Swaggo 支持使用注释在 Go 代码中直接描述 API 接口。开发者可以根据自己的需求添加注释，并且 Swaggo 会解析这些注释，生成 OpenAPI 格式的文档。
Swaggo 提供了一个 web 界面（通常是 /swagger 路径），可以通过这个界面来查看 API 的详细文档并进行交互式测试。这个功能是基于 Swagger UI 的，因此可以直接在浏览器中查看 API 详情，进行测试请求。
Swaggo 可以很容易地与流行的 Go Web 框架（如 Gin、Echo 等）集成。通过一些简单的配置，Swaggo 就能够自动解析 API 路由，并生成文档。
Swaggo 允许开发者自定义 API 文档的生成规则，比如修改 API 的描述、标签、版本等。
安装 Swaggo 工具
Life is like a journey
go get -u github.com/swaggo/swag/cmd/swag
为 API 添加注释 在 Go 的 handler 函数上，使用特定的注释格式描述 API 的信息。例如：
// @Summary 获取用户信息
// @Description 根据用户ID获取用户的详细信息
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} User
// @Failure 400 {object} Error
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
// 实现代码
}
生成文档 在项目根目录运行：
swag init
这会扫描代码中的注释，生成 docs 文件夹，其中包含了生成的 OpenAPI 文档。
集成到 Web 框架 以 Gin 为例，Swaggo 可以通过以下代码集成：
import (
"github.com/gin-gonic/gin"
_ "your_project/docs" // 引入 docs 包
swag "github.com/swaggo/gin-swagger"
ginSwagger "github.com/swaggo/gin-swagger/swaggerFiles"
)
func main() {
router := gin.Default()
// 设置 Swagger 文档路由
router.GET("/swagger/*any", ginSwagger.WrapHandler(ginSwagger.Files))
// 其他路由定义
router.Run(":8080")
}
访问 Swagger UI 运行应用后，可以访问 http://localhost:8080/swagger/index.html 来查看生成的 API 文档，并通过 Swagger UI 与 API 交互。
├── main.go
├── docs
│ └── docs.go
├── go.mod
└── go.sum
总的来说，Swaggo 是一个非常方便的工具，尤其适合需要快速生成和维护 API 文档的 Go 项目。