Gin 实战 4：Swagger 接口文档

接口多起来之后，不能只靠口头约定。Swagger 可以把接口路径、请求参数、响应结构生成在线文档。

1. 安装依赖

go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files
go install github.com/swaggo/swag/cmd/swag@latest

2. 给入口添加项目信息

在 main.go 顶部添加注释：

// @title youlai-gin API
// @version 1.0
// @description Gin 从0到1实战接口文档
// BasePath 表示所有业务接口的公共前缀。
// @BasePath /api/v1

3. 给接口添加注释

// Hello 第一个接口
// @Summary 第一个接口
// Tags 用于在 Swagger 页面中给接口分组。
// @Tags 示例
// Produce 表示接口返回 JSON。
// @Produce json
// Success 描述成功响应结构；前期可以先用 map，后续再换成具体结构体。
// @Success 200 {object} map[string]interface{}
// Router 路径要写去掉 BasePath 之后的部分。
// @Router /hello [get]
func Hello(c *gin.Context) {
    c.JSON(200, gin.H{
        "code": "00000",
        "msg":  "成功",
        "data": gin.H{"message": "Hello, youlai-gin"},
    })
}

4. 注册 Swagger 路由

在 main.go 引入生成包和 Swagger Handler：

import (
    // 这个空导入很关键：它会触发 api 包的 init()，注册 Swagger 元信息。
    _ "youlai-gin/api"

    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

注册路由：

// /swagger/*any 是 Swagger UI 和 swagger.json 的访问入口。
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

生成文档：

swag init -g main.go -o api
go run main.go

访问：

http://localhost:8000/swagger/index.html

下一章接入应用日志与请求追踪，学习如何从控制台和日志文件中定位问题。