本示例演示如何使用 github.com/darkit/gin 的 Swagger 文档生成功能。

• ✅ 支持 OpenAPI 3.0 规范
• ✅ 链式调用的路由注解
• ✅ 自动生成 Swagger UI 界面
• ✅ 支持参数、响应、标签定义
• ✅ 支持模型自动解析
• ✅ 支持安全认证定义
• ✅ 支持废弃路由标记

e := gin.New(
    gin.EnableSwagger(swagger.SwaggerConfig{
        Title:       "我的 API",
        Description: "API 文档描述",
        Version:     "v1.0.0",
        BasePath:    "/api",
        Host:        "localhost:8080",
        Schemes:     []string{"http", "https"},
    }),
)

e.Router().GET("/users", listUsers).
    Doc("获取用户列表").
    Description("分页获取所有用户信息").
    Param("page", "query", "integer", "页码", false).
    Param("per_page", "query", "integer", "每页数量", false).
    Response(200, "成功", []User{}).
    Tag("用户管理")

启动服务器后，访问：

• Swagger UI: http://localhost:8080/swagger
• JSON 文档: http://localhost:8080/swagger/doc.json

设置路由的简要说明

.Doc("获取用户列表")

设置路由的详细描述

.Description("分页获取所有用户信息，支持按名称搜索")

添加参数定义

参数位置 (in):

• query - 查询参数
• path - 路径参数
• header - 请求头参数
• body - 请求体参数

参数类型 (typ):

• string - 字符串
• integer - 整数
• number - 数字
• boolean - 布尔值
• array - 数组
• object - 对象

示例：

.Param("id", "path", "integer", "用户ID", true)
.Param("page", "query", "integer", "页码", false)
.Param("X-API-Key", "header", "string", "API密钥", true)

添加带模型的参数定义（用于 body 参数）

.ParamModel("body", "body", "用户信息", true, User{})

添加响应定义

.Response(200, "成功", User{})
.Response(400, "参数错误", ErrorResponse{})
.Response(404, "用户不存在", ErrorResponse{})

添加标签（用于分组）

.Tag("用户管理", "权限管理")

标记为废弃 API

.Deprecated()

设置安全方案

.Security("apiKey")

使用结构体标签来增强文档：

type User struct {
    ID    int64  `json:"id" description:"用户ID"`
    Name  string `json:"name" binding:"required" description:"用户名"`
    Email string `json:"email" description:"邮箱地址"`
    Age   int    `json:"age" description:"年龄"`
}

• json - JSON 字段名
• description - 字段描述
• binding:"required" - 标记为必需字段

cd examples/swagger-demo
go run main.go

然后访问 http://localhost:8080/swagger 查看 Swagger UI。

详见 main.go 文件，包含：

1. 用户列表（GET /api/users）
2. 用户详情（GET /api/users/:id）
3. 创建用户（POST /api/users）
4. 更新用户（PUT /api/users/:id）
5. 删除用户（DELETE /api/users/:id）
6. 搜索用户（GET /api/users/search）- 带安全认证
7. 旧版 API（GET /api/v1/users）- 标记为废弃

1. 链式调用顺序: 路由注解方法必须在路由定义之后立即调用
2. 模型引用: Response 和 ParamModel 会自动解析结构体生成 Schema
3. 动态生成: 文档在访问时动态生成，确保始终是最新的
4. 性能影响: 文档生成仅在访问 Swagger 端点时进行，不影响业务 API 性能