27-集成swagger接口文档

安装工具

go install github.com/swaggo/swag/cmd/swag@latest

验证安装（查看版本）

swag version

如果使用 Gin 框架，安装 gin-swagger 和 swaggo/files（提供 Swagger UI 静态资源）

txt 复制代码

go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

初始化

初始化 Swagger 配置

在项目根目录执行以下命令，生成 Swagger 基础配置文件（docs 文件夹，含 docs.go、swagger.json、swagger.yaml）
swag init
- 在根目录下执行奥

编写注释

是通过注释形成文档的
注释分类
- 项目全局注释（main.go 中）：描述项目整体信息
- 接口注释（每个 API handler 上方）：描述接口路径、参数、响应等

txt 复制代码

// 全局注释

注释标签	     说明								示例
@title		文档标题（必填）				 @title Gin-Swaggo API 示例
@version	API 版本（必填）					      @version 1.0
@description	项目描述				@description 基于 Gin 的用户管理 API
@host		API 服务地址（如 localhost:8080）	         @host localhost:8080
@BasePath	接口基础路径（所有接口前缀）		           @BasePath /api/v1
@contact.name	联系人名称			                   @contact.name 开发者
@contact.email	联系人邮箱					@contact.email dev@example.com
@license.name	许可证名称					@license.name Apache 2.0

txt 复制代码

// ### 接口注释（每个 handler 上方）
package models
注释标签				说明			       示例
@Summary			接口简介（简短描述）		   @Summary 查询用户详情
@Description			接口详细描述		@Description 根据用户ID获取用户信息
@Tags				接口分组（多个标签用逗号分隔）	       @Tags 用户管理,查询
@Accept	请求数据格式（如 json、form-data）	                   @Accept json
@Produce				响应数据格式（如 json、xml）	@Produce json
@Param					接口参数（格式：名称 位置 类型 是否必填 描述）	
                                        路径参数：@Param id path uint true "用户ID"；
                                  Body 参数：@Param user body UserRequest true "用户信息"；
                                        Query 参数：@Param name query string false "用户名"

@Success				成功响应（格式：状态码 {类型} 模型 描述）	@Success 200 {object} UserResponse "成功返回"
@Failure				失败响应（格式同 @Success）	@Failure 400 {object} map[string]string "参数错误"
@Router					接口路径 + 请求方法（相对 BasePath）	@Router /user/{id} [get]
@Security				接口认证（如 JWT）	@Security ApiKeyAuth

案例如下

main.go

go 复制代码

package models

package main

import (
        "lsgo/router"
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "your-project-path/docs" // 必须导入 docs 目录（替换为实际项目路径）
	"net/http"
)

// 项目全局注释（main.go 中，swag init 会扫描）
// @title           Gin-Swaggo API 示例
// @version         1.0
// @description     这是一个基于 Gin + Swaggo 的 API 文档示例//描述
// @termsOfService  http://swagger.io/terms/
// @contact.name    开发者// 名字
// @contact.email   dev@example.com//邮箱
// @license.name    Apache 2.0
// @license.url     http://www.apache.org/licenses/LICENSE-2.0.html
// @host            localhost:8080  // API 服务地址（访问文档时默认拼接）有环境的用服务器地址
// @BasePath        /api/v1  // 接口基础路径（所有接口路径前缀）
func main() {
	r := gin.Default()
        // 只在开发环境启用 Swagger 看个人情况
	if os.Getenv("GIN_MODE") != "release" {
	    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	}

	// 注册 Swagger UI 路由（访问路径：http://localhost:8080/swagger/index.html）
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	// 接口路由（基础路径 /api/v1）
	v1 := r.Group("/api/v1")
	{
		user := v1.Group("/user")
		{
			user.GET("/:id", router.GetUser)       // 查单个用户
			user.POST("", router.CreateUser)      // 创建用户
			user.PUT("/:id", router.UpdateUser)   // 更新用户
			user.DELETE("/:id", router.DeleteUser)// 删除用户
		}
	}
	r.Run(":8080")
}

router/user.go

go 复制代码

package router

import (
	"github.com/gin-gonic/gin"
	"net/http"
)


// 定义请求/响应结构体（需添加注释，swag 会识别为 Schema）
// UserRequest 创建/更新用户的请求体
type UserRequest struct {
	// 用户名（必填）
	Username string `json:"username" binding:"required"`
	// 年龄（必填，最小值 1）
	Age int `json:"age" binding:"required,min=1"`
	// 邮箱（可选）
	Email string `json:"email,omitempty"`
}

// UserResponse 用户响应结构体
type UserResponse struct {
	// 用户ID
	ID       uint   `json:"id"`
	// 用户名
	Username string `json:"username"`
	// 年龄
	Age      int    `json:"age"`
	// 邮箱
	Email    string `json:"email,omitempty"`
	// 响应状态
	Status   string `json:"status"`
}

// GetUser 查单个用户
// @Summary      查询用户详情
// @Description  根据用户ID获取用户信息
// @Tags         用户管理  // 接口分类（文档中按 Tags 分组）
// @Accept       json
// @Produce      json
// @Param        id   path      uint   true  "用户ID"  // path 参数（true 表示必填）
// @Success      200  {object}  UserResponse  "成功返回用户信息"
// @Failure      400  {object}  map[string]string  "请求参数错误"
// @Failure      404  {object}  map[string]string  "用户不存在"
// @Router       /user/{id} [get]  // 接口路径（相对 BasePath）
func GetUser(c *gin.Context) {
	id := c.Param("id")
	// 模拟业务逻辑
	c.JSON(http.StatusOK, UserResponse{
		ID:       1,
		Username: "张三",
		Age:      25,
		Email:    "zhangsan@example.com",
		Status:   "success",
	})
}

// CreateUser 创建用户
// @Summary      创建用户
// @Description  新增用户（用户名和年龄为必填）
// @Tags         用户管理
// @Accept       json
// @Produce      json
// @Param        user  body      UserRequest  true  "用户信息"  // body 参数
// @Success      201  {object}  UserResponse  "创建成功"
// @Failure      400  {object}  map[string]string  "请求参数错误"
// @Router       /user [post]
func CreateUser(c *gin.Context) {
	var req UserRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	// 模拟入库逻辑
	c.JSON(http.StatusCreated, UserResponse{
		ID:       2,
		Username: req.Username,
		Age:      req.Age,
		Email:    req.Email,
		Status:   "created",
	})
}

// UpdateUser 更新用户
// @Summary      更新用户
// @Description  根据ID更新用户信息
// @Tags         用户管理
// @Accept       json
// @Produce      json
// @Param        id    path      uint         true  "用户ID"
// @Param        user  body      UserRequest  true  "更新的用户信息"
// @Success      200  {object}  UserResponse  "更新成功"
// @Failure      400  {object}  map[string]string  "请求参数错误"
// @Failure      404  {object}  map[string]string  "用户不存在"
// @Router       /user/{id} [put]
func UpdateUser(c *gin.Context) {
	id := c.Param("id")
	var req UserRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	// 模拟更新逻辑
	c.JSON(http.StatusOK, UserResponse{
		ID:       1,
		Username: req.Username,
		Age:      req.Age,
		Email:    req.Email,
		Status:   "updated",
	})
}

// DeleteUser 删除用户
// @Summary      删除用户
// @Description  根据ID删除用户
// @Tags         用户管理
// @Accept       json
// @Produce      json
// @Param        id  path      uint   true  "用户ID"
// @Success      200  {object}  map[string]string  "删除成功"
// @Failure      404  {object}  map[string]string  "用户不存在"
// @Router       /user/{id} [delete]
func DeleteUser(c *gin.Context) {
	id := c.Param("id")
	// 模拟删除逻辑
	c.JSON(http.StatusOK, gin.H{"status": "deleted", "user_id": id})
}


// @ignore  // 忽略该接口，不生成文档
//func Test(c *gin.Context) { ... }

每次更新都需要重新生成生成文档

swag init (在根目录执行)
若注释无语法错误，会更新 docs 目录下的 swagger.json/swagger.yaml

启动服务

go run main.go
浏览器访问**http://localhost:8080/swagger/index.html**地址就可以查看文档了