Gin框架整合Swagger生成接口文档完整指南

# 安装swag命令行工具（需要Go 1.16+）
go install github.com/swaggo/swag/cmd/swag@latest

# 安装gin-swagger中间件
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

// @title 用户管理API
// @version 1.0
// @description 这是一个用户管理的API文档
// @termsOfService http://example.com/terms/
// @contact.name API Support
// @contact.url http://example.com/support
// @contact.email support@example.com
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /api/v1
// @schemes http https
package main

import (
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
    _ "your-project/docs" // 重要：导入自动生成的docs包
)

func main() {
    r := gin.Default()
    
    // 配置Swagger路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
    // 您的API路由配置
    // ...
    
    r.Run(":8080")
}

// User 用户模型
// @Description 用户基本信息
type User struct {
    ID       int    `json:"id" example:"1"`       // 用户ID
    Username string `json:"username" example:"zhangsan"` // 用户名
    Email    string `json:"email" example:"zhangsan@example.com"` // 用户邮箱
    Age      int    `json:"age" example:"25"`     // 用户年龄
}

// ErrorResponse 错误响应
// @Description 接口错误时的返回信息
type ErrorResponse struct {
    Code    int    `json:"code" example:"400"`
    Message string `json:"message" example:"请求参数错误"`
}

// GetUserByID 
// @Summary 获取指定用户信息
// @Description 根据用户ID获取用户信息
// @Tags 用户相关
// @Accept json
// @Produce json
// @Param id path int true "用户ID" minimum(1)
// @Param x-token header string true "认证Token"
// @Success 200 {object} User "成功"
// @Failure 400 {object} ErrorResponse "请求参数错误"
// @Failure 404 {object} ErrorResponse "未找到用户"
// @Router /users/{id} [get]
func GetUserByID(c *gin.Context) {
    // 处理逻辑
}

// GetUsers 
// @Summary 获取用户列表
// @Description 获取符合条件的用户列表，支持分页和筛选
// @Tags 用户相关
// @Accept json
// @Produce json
// @Param page query int false "页码" default(1)
// @Param size query int false "每页数量" default(10) maximum(100)
// @Param name query string false "用户姓名"
// @Success 200 {array} User "用户列表"
// @Failure 400 {object} ErrorResponse "请求参数错误"
// @Router /users [get]
func GetUsers(c *gin.Context) {
    // 处理逻辑
}

// CreateUser 
// @Summary 创建用户
// @Description 创建新的用户
// @Tags 用户相关
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 201 {object} User "创建成功"
// @Failure 400 {object} ErrorResponse "请求参数错误"
// @Failure 500 {object} ErrorResponse "内部服务器错误"
// @Router /users [post]
func CreateUser(c *gin.Context) {
    var user User
    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // 创建用户的逻辑...
    c.JSON(201, user)
}

// UpdateUser 
// @Summary 更新用户信息
// @Description 更新指定用户的信息
// @Tags 用户相关
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Param user body User true "用户信息"
// @Success 200 {object} User "更新成功"
// @Failure 400 {object} ErrorResponse "请求参数错误"
// @Failure 404 {object} ErrorResponse "未找到用户"
// @Router /users/{id} [put]
func UpdateUser(c *gin.Context) {
    // 处理逻辑
}

// DeleteUser 
// @Summary 删除用户
// @Description 删除指定用户
// @Tags 用户相关
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 204 "删除成功"
// @Failure 404 {object} ErrorResponse "未找到用户"
// @Router /users/{id} [delete]
func DeleteUser(c *gin.Context) {
    // 处理逻辑
}

// @Param id path int true "用户ID" minimum(1) maximum(10000)
// @Param page query int false "页码" default(1) minimum(1)
// @Param size query int false "每页数量" default(10) maximum(100)
// @Param Authorization header string true "认证令牌" example("Bearer JWT_TOKEN")
// @Param user body User true "用户信息"

# 基本命令
swag init

# 如果main函数在其他位置
swag init -g cmd/server/main.go

# 解析依赖和内部包（大型项目推荐）
swag init --parseDependency --parseInternal

r.GET("/swagger/*any", ginSwagger.WrapHandler(
    swaggerFiles.Handler,
    ginSwagger.URL("/swagger/doc.json"), // 自定义文档JSON路径
    ginSwagger.DocExpansion("list"),    // 文档展开方式：list/full/none
    ginSwagger.DefaultModelsExpandDepth(1), // 模型默认展开深度
    ginSwagger.PersistAuthorization(true),   // 保持授权信息
))

func main() {
    r := gin.Default()
    
    // 非生产环境才启用Swagger
    if gin.Mode() != gin.ReleaseMode {
        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    }
    
    // ...其他路由配置
    r.Run(":8080")
}

// main.go
import (
    _ "github.com/your-username/your-project/docs"
    _ "github.com/your-username/your-project/api/user/docs" // 用户模块API文档
    _ "github.com/your-username/your-project/api/order/docs" // 订单模块API文档
)

swag init --parseDependency --parseInternal

// 标准响应格式
type StandardResponse struct {
    Code    int         `json:"code" example:"200"`
    Message string      `json:"message" example:"success"`
    Data    interface{} `json:"data"`
}

// 分页响应格式
type PaginatedResponse struct {
    Page      int         `json:"page" example:"1"`
    PageSize  int         `json:"pageSize" example:"10"`
    Total     int64       `json:"total" example:"100"`
    TotalPage int         `json:"totalPage" example:"10"`
    Data      interface{} `json:"data"`
}

// 在注解中使用
// @Success 200 {object} StandardResponse{data=User} "成功获取用户信息"
// @Success 200 {object} PaginatedResponse{data=[]User} "成功获取用户列表"