- 微信
- 微博
  
  分享文章到微博
- 复制链接
  
  复制链接到剪贴板

github.com/swaggo/gin-swagger 如何使用

鱼弦发表于 2025/06/19 11:22:20 2025/06/19

【摘要】 github.com/swaggo/gin-swagger 是一个用于在基于框架的 Go Web 应用中集成文档的工具。通过它，你可以自动生成、展示和交互式地测试你的 API 文档。以下是详细的指南，涵盖从安装、配置到使用的完整步骤。1. 简介Swagger 是一种用于设计、构建、记录和使用 RESTful Web 服务的工具集。通过 Swagger，你可以：描述你的 A...

github.com/swaggo/gin-swagger 是一个用于在基于框架的 Go Web 应用中集成文档的工具。通过它，你可以自动生成、展示和交互式地测试你的 API 文档。以下是详细的指南，涵盖从安装、配置到使用的完整步骤。

1. 简介

Swagger 是一种用于设计、构建、记录和使用 RESTful Web 服务的工具集。通过 Swagger，你可以：

描述你的 API：使用 YAML 或 JSON 格式的规范文件。
生成交互式文档：通过 Swagger UI，开发者可以直观地查看和测试 API。
生成客户端 SDK：支持多种编程语言。

github.com/swaggo/gin-swagger 是 Gin 框架的一个中间件，用于将 Swagger UI 集成到你的 Go Web 应用中，方便开发者查看和测试 API 文档。

2. 前提条件

在开始之前，确保你已经具备以下环境和工具：

Go 环境：建议使用 Go 1.16 或更高版本。
Gin 框架：用于构建 Web 应用。
swag 工具：用于生成 Swagger 文档。
基本的 Gin 应用：如果你还没有 Gin 应用，可以参考创建一个简单的应用。

3. 安装

3.1 安装 Gin 框架

如果尚未安装 Gin，可以使用以下命令安装：

go get -u github.com/gin-gonic/gin

3.2 安装 `swaggo/gin-swagger`

使用 go get 安装 gin-swagger 及其依赖：

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/swag/cmd/swag

注意：

github.com/swaggo/swag/cmd/swag 是 swag 命令行工具，用于生成 Swagger 文档。

github.com/swaggo/gin-swagger 是 Gin 的 Swagger 中间件。

3.3 安装 `swag` 工具

swag 是一个命令行工具，用于根据代码中的注释生成 Swagger 文档。确保 swag 已正确安装，并添加到系统的 PATH 中。

验证安装：

swag --version

如果未安装或无法识别命令，请重新执行安装步骤：

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

确保 $GOPATH/bin 已添加到你的 PATH 环境变量中。例如，在 ~/.bashrc 或 ~/.zshrc 中添加：

export PATH=$PATH:$(go env GOPATH)/bin

然后重新加载 shell 配置：

source ~/.bashrc    # 或者 source ~/.zshrc

4. 项目结构示例

为了便于理解，以下是一个简单的项目结构示例：

my-gin-app/
├── main.go
├── go.mod
├── go.sum
├── docs/                  # Swagger 文档将生成在此目录
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
└── handlers/              # 处理器目录（可选）
    └── treasure.go

注意：docs/ 目录将由 swag 工具自动生成，无需手动创建。

5. 使用 `swag` 生成 Swagger 文档

5.1 安装 `swag` 工具

如前所述，确保已安装 swag 工具并添加到 PATH 中。

验证安装：

swag --version

应输出类似：

swag version v1.8.10

5.2 添加 Swagger 注释

为了让 swag 能够生成正确的 Swagger 文档，你需要在代码中添加特定的注释。这些注释遵循规范。

5.2.1 在 `main.go` 中添加注释

打开 main.go 并添加必要的 Swagger 注释。以下是一个示例：

package main

import (
    "github.com/gin-gonic/gin"
    _ "github.com/swaggo/gin-swagger"                   // 导入 gin-swagger 包
    _ "github.com/swaggo/gin-swagger/swaggerFiles"      // 导入 swaggerFiles 包
    "github.com/swaggo/swag/cmd/swag"                   // 不需要导入，仅用于生成文档
    // 其他导入...
)

// @title My Gin API
// @version 1.0
// @description 这是一个使用 Gin 和 Swagger 的示例 API。
// @host localhost:8080
// @BasePath /
func main() {
    r := gin.Default()

    // 注册 Swagger 路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // 注册你的路由
    // 例如：
    // r.GET("/treasures", GetTreasures)
    // r.GET("/treasures/:id", GetTreasureByID)

    // 启动服务器
    r.Run(":8080")
}

// 以下是示例处理器函数及其注释（将在后续步骤中添加）

注释说明：

@title：API 的标题。
@version：API 的版本。
@description：API 的描述。
@host：API 的主机地址（包括端口）。
@BasePath：API 的基础路径。

注意：

这些注释必须放在 main 函数 之前，通常放在文件的顶部。

确保注释格式正确，swag 工具依赖这些注释生成文档。

5.2.2 在处理器函数中添加注释

假设你有一个 Treasure 相关的 API，以下是如何为这些 API 添加 Swagger 注释的示例。

首先，在 handlers/ 目录下创建一个 treasure.go 文件（如果尚未存在），并定义处理函数及其注释。

// handlers/treasure.go

package handlers

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

// Treasure 结构体定义
type Treasure struct {
    Id         int64 `json:"id"`          // 唯一ID，自增
    UserId     int   `json:"userid"`      // 玩家ID
    TreasureId int   `json:"treasure_id"` // 宝库ID
    Count      int   `json:"count"`       // 数量
    Active     int   `json:"active"`      // 是否已激活
    Level      int   `json:"level"`       // 等级
    StarLv     int   `json:"star_lv"`     // 星级
    ActiveAt   int64 `json:"active_at"`   // 激活时间
    CreatedAt  int64 `json:"created_at"`  // 创建时间
    UpdatedAt  int64 `json:"updated_at"`  // 更新时间
}

// @Summary 获取所有宝藏
// @Description 获取所有宝藏的列表
// @Tags Treasures
// @Accept json
// @Produce json
// @Success 200 {array} Treasure
// @Router /treasures [get]
func GetTreasures(c *gin.Context) {
    // 示例数据，实际应从数据库获取
    treasures := []Treasure{
        {
            Id:         1,
            UserId:     101,
            TreasureId: 1,
            Count:      5,
            Active:     1,
            Level:      3,
            StarLv:     2,
            ActiveAt:   1633072800,
            CreatedAt:  1633072000,
            UpdatedAt:  1633072800,
        },
        {
            Id:         2,
            UserId:     101,
            TreasureId: 2,
            Count:      3,
            Active:     0,
            Level:      2,
            StarLv:     1,
            ActiveAt:   0,
            CreatedAt:  1633072100,
            UpdatedAt:  1633072100,
        },
    }
    c.JSON(http.StatusOK, treasures)
}

// @Summary 获取单个宝藏
// @Description 根据 ID 获取单个宝藏的详细信息
// @Tags Treasures
// @Accept json
// @Produce json
// @Param id path int true "宝藏ID"
// @Success 200 {object} Treasure
// @Failure 404 {object} map[string]string
// @Router /treasures/{id} [get]
func GetTreasureByID(c *gin.Context) {
    id := c.Param("id")
    // 示例数据，实际应从数据库获取
    treasure := Treasure{
        Id:         1,
        UserId:     101,
        TreasureId: 1,
        Count:      5,
        Active:     1,
        Level:      3,
        StarLv:     2,
        ActiveAt:   1633072800,
        CreatedAt:  1633072000,
        UpdatedAt:  1633072800,
    }
    c.JSON(http.StatusOK, treasure)
}

注释说明：

@Summary：API 的简要描述。
@Description：API 的详细描述。
@Tags：用于分组 API，方便在 Swagger UI 中分类显示。
@Accept：客户端应接受的请求内容类型。
@Produce：服务器将产生的响应内容类型。
@Success：成功的响应状态码及返回的数据结构。
@Failure：失败的响应状态码及返回的数据结构。
@Param：定义路径参数、查询参数、请求体等。
@Router：定义 API 的路由路径及 HTTP 方法。

注意：

确保每个处理器函数都有相应的 Swagger 注释。

@Param 的使用需要根据实际情况定义参数类型（路径、查询、请求体等）。

5.3 生成 Swagger 文档

在添加完所有必要的 Swagger 注释后，可以使用 swag 工具生成 Swagger 文档。

5.3.1 在项目根目录执行 `swag init`

确保你在项目的根目录（即包含 main.go 的目录）下执行以下命令：

swag init

输出示例：

2024/04/27 12:34:56 Generate swagger docs....
2024/04/27 12:34:56 Create docs/docs.go
2024/04/27 12:34:56 Create docs/swagger.json
2024/04/27 12:34:56 Create docs/swagger.yaml
2024/04/27 12:34:56 Successfully generated docs

这将在项目根目录下生成一个 docs/ 目录，包含以下文件：

docs.go：包含 Swagger 文档的 Go 代码。
swagger.json：Swagger 2.0 规范的 JSON 格式文档。
swagger.yaml：Swagger 2.0 规范的 YAML 格式文档。

5.3.2 确保 `docs` 目录被正确导入

为了使 gin-swagger 能够访问生成的 Swagger 文档，需要在 main.go 中导入 docs 包。即使你不直接使用 docs 包中的内容，导入它也会确保 go build 包含 docs 目录中的文件。

修改 main.go 的导入部分：

package main

import (
    "github.com/gin-gonic/gin"
    _ "github.com/swaggo/gin-swagger"                   // 导入 gin-swagger 包
    _ "github.com/swaggo/gin-swagger/swaggerFiles"      // 导入 swaggerFiles 包
    _ "my-gin-app/docs"                                 // 导入生成的 docs 包（替换为你的模块路径）
    // 其他导入...
)

// @title My Gin API
// @version 1.0
// @description 这是一个使用 Gin 和 Swagger 的示例 API。
// @host localhost:8080
// @BasePath /
func main() {
    r := gin.Default()

    // 注册 Swagger 路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // 注册你的路由
    // 例如：
    // r.GET("/treasures", GetTreasures)
    // r.GET("/treasures/:id", GetTreasureByID)

    // 启动服务器
    r.Run(":8080")
}

注意：
将 "my-gin-app/docs" 替换为你的 Go 模块的路径。如果你的项目不在 GOPATH 中，或者使用了 Go Modules，确保路径正确。
如果你不确定模块路径，可以在项目根目录下查看 go.mod 文件中的 module 声明。例如：
module github.com/yourusername/my-gin-app
那么导入路径应为 "github.com/yourusername/my-gin-app/docs"。

5.3.3 确保 `ginSwagger` 能访问文档

由于 gin-swagger 需要访问 docs/docs.go 中的 Swagger 文档，确保 docs 包被正确导入，即使你不直接使用它。

6. 集成 `gin-swagger` 到 Gin 应用

现在，你已经添加了 Swagger 注释并生成了文档，接下来需要将 gin-swagger 中间件集成到你的 Gin 应用中，以便通过 /swagger 路径访问 Swagger UI。

6.1 修改 `main.go` 以注册 Swagger 路由

确保在 main.go 中已经添加了以下代码：

package main

import (
    "github.com/gin-gonic/gin"
    _ "github.com/swaggo/gin-swagger"                   // 导入 gin-swagger 包
    _ "github.com/swaggo/gin-swagger/swaggerFiles"      // 导入 swaggerFiles 包
    _ "github.com/yourusername/my-gin-app/docs"         // 替换为你的模块路径
    // 其他导入...
)

// @title My Gin API
// @version 1.0
// @description 这是一个使用 Gin 和 Swagger 的示例 API。
// @host localhost:8080
// @BasePath /
func main() {
    r := gin.Default()

    // 注册 Swagger 路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // 注册你的 API 路由
    // 例如，假设你在 handlers 包中定义了 GetTreasures 和 GetTreasureByID 函数
    // 首先需要导入 handlers 包
    // import "github.com/yourusername/my-gin-app/handlers"

    // r.GET("/treasures", handlers.GetTreasures)
    // r.GET("/treasures/:id", handlers.GetTreasureByID)

    // 启动服务器
    r.Run(":8080")
}

注意：

确保导入了 handlers 包（如果你的处理器函数在 handlers 目录下）。

如果你尚未创建路由，可以暂时注释掉 r.GET 部分，专注于 Swagger UI 的访问。

6.2 注册 API 路由

为了完整示例，假设你在 handlers 包中定义了 GetTreasures 和 GetTreasureByID 函数，现在需要在 main.go 中注册这些路由。

修改 main.go：

package main

import (
    "github.com/gin-gonic/gin"
    _ "github.com/swaggo/gin-swagger"                   // 导入 gin-swagger 包
    _ "github.com/swaggo/gin-swagger/swaggerFiles"      // 导入 swaggerFiles 包
    _ "github.com/yourusername/my-gin-app/docs"         // 替换为你的模块路径
    "github.com/yourusername/my-gin-app/handlers"       // 导入 handlers 包
)

// @title My Gin API
// @version 1.0
// @description 这是一个使用 Gin 和 Swagger 的示例 API。
// @host localhost:8080
// @BasePath /
func main() {
    r := gin.Default()

    // 注册 Swagger 路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // 注册 API 路由
    r.GET("/treasures", handlers.GetTreasures)
    r.GET("/treasures/:id", handlers.GetTreasureByID)

    // 启动服务器
    r.Run(":8080")
}

注意：

确保 handlers 包中的函数是导出的（首字母大写），以便在 main.go 中访问。

如果 handlers 包位于不同的模块或路径，请确保导入路径正确。

7. 访问 Swagger UI

完成上述步骤后，你可以启动你的 Gin 应用，并通过浏览器访问 Swagger UI 来查看和测试你的 API 文档。

7.1 启动 Gin 应用

在项目根目录下运行：

go run main.go

你应该会看到类似如下的输出：

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 [GIN-debug] GET    /swagger/*any             --> github.com/swaggo/gin-swagger.WrapHandler.func1 (3 handlers)
 [GIN-debug] GET    /treasures                --> github.com/yourusername/my-gin-app/handlers.GetTreasures (3 handlers)
 [GIN-debug] GET    /treasures/:id            --> github.com/yourusername/my-gin-app/handlers.GetTreasureByID (3 handlers)
[GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
[GIN-debug] Listening and serving HTTP on :8080

7.2 打开浏览器访问 Swagger UI

在浏览器中访问：

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

你应该会看到 Swagger UI 界面，展示了你定义的所有 API，包括 GET /treasures 和 GET /treasures/{id}。

Swagger UI 界面示例：

API 列表：左侧面板显示所有定义的 API 标签和路径。
API 详情：点击某个 API，右侧面板显示该 API 的详细信息，包括请求参数、响应结构、示例等。
交互式测试：你可以直接在 Swagger UI 中发送请求，查看响应结果。

8. 常见问题及解决方案

在使用 swaggo/gin-swagger 的过程中，可能会遇到一些常见问题。以下是一些常见问题及其解决方案。

问题 1：访问 `http://localhost:8080/swagger/index.html` 显示 404 或空白页面

可能原因：

Swagger 文档未正确生成：swag init 未成功执行，或 docs 目录未生成。
导入路径错误：main.go 中导入 docs 包的路径不正确，导致 docs.go 未被包含在编译中。
ginSwagger.WrapHandler 未正确注册：路由注册有误。

解决方案：

确保 swag init 成功执行：
- 在项目根目录下运行 swag init，确保没有错误输出，并且 docs/ 目录已生成。
- 检查 docs/ 目录下是否存在 docs.go、swagger.json 和 swagger.yaml 文件。
检查导入路径：
- 确保 main.go 中导入 docs 包的路径与你的 Go 模块路径一致。
- 例如，如果你的 go.mod 中声明：
```
module github.com/yourusername/my-gin-app
```
  那么导入路径应为：
```
_ "github.com/yourusername/my-gin-app/docs"
```
确保 ginSwagger.WrapHandler 正确注册：
- 确认在 main.go 中有以下代码：
```
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
```
清除编译缓存并重新运行：
- 有时，旧的编译缓存可能导致问题。可以尝试删除 go build 的缓存并重新运行：
```
go clean -cache
go run main.go
```

问题 2：Swagger UI 显示 API 但无法访问（404 错误）

可能原因：

API 路由未正确注册：在 main.go 中未注册相应的处理器函数。
处理器函数路径或方法错误：定义的路由与实际处理器函数的路径或 HTTP 方法不匹配。

解决方案：

确保 API 路由已正确注册：
- 在 main.go 中，确保已注册 GET /treasures 和 GET /treasures/:id 路由。
- 例如：
```
r.GET("/treasures", handlers.GetTreasures)
r.GET("/treasures/:id", handlers.GetTreasureByID)
```

检查处理器函数定义：

确保处理器函数在 handlers 包中正确定义，并且是导出的（首字母大写）。

例如，handlers/treasure.go 中：

package handlers

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

// GetTreasures 处理函数
func GetTreasures(c *gin.Context) {
    // 实现逻辑
}

// GetTreasureByID 处理函数
func GetTreasureByID(c *gin.Context) {
    // 实现逻辑
}

确保处理器函数路径与路由匹配：
- 例如，如果路由定义为 GET /treasures/:id，则处理器函数应接受 id 作为路径参数，并正确处理。

问题 3：Swagger UI 中 API 参数或响应不正确

可能原因：

Swagger 注释不完整或不正确：注释中缺少必要的字段，或字段定义错误。
处理器函数实际实现与注释不符：例如，注释中定义了某个参数，但处理器函数未处理该参数。

解决方案：

检查 Swagger 注释：
- 确保每个处理器函数都有完整的 Swagger 注释，包括 @Summary、@Description、@Tags、@Accept、@Produce、@Param、@Success、@Failure 和 @Router 等。
- 特别是 @Param 部分，确保参数类型、位置（路径、查询、请求体等）正确。
确保处理器函数实现与注释一致：
- 例如，如果注释中定义了 @Param id path int true "宝藏ID"，则处理器函数应从路径中获取 id 参数，并在逻辑中使用它。
重新生成 Swagger 文档：
- 在修改 Swagger 注释或处理器函数后，重新运行 swag init 以更新文档。
```
swag init
```

问题 4：`swag init` 报错或无法识别注释

可能原因：

注释格式错误：Swagger 注释不符合规范，导致 swag 工具无法解析。
swag 工具版本问题：使用的 swag 版本与项目不兼容。
代码结构问题：注释位置不正确，或代码中存在语法错误。

解决方案：

检查注释格式：
- 确保所有 Swagger 注释以 // @ 开头，并且格式正确。
- 参考确保注释符合规范。
更新 swag 工具：
- 确保使用最新版本的 swag 工具。
```
go install github.com/swaggo/swag/cmd/swag@latest
```
检查代码语法：
- 确保 main.go 和其他相关文件没有语法错误，Go 编译器能够成功编译。
查看 swag 输出日志：
- 运行 swag init 时，注意查看控制台输出，寻找错误信息或警告，根据提示进行修正。

9. 完整示例代码

为了更直观地理解如何使用 swaggo/gin-swagger，以下是一个完整的示例项目代码。

9.1 项目结构

my-gin-app/
├── main.go
├── go.mod
├── go.sum
├── docs/                  # Swagger 文档将生成在此目录
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
└── handlers/
    └── treasure.go

9.2 `go.mod` 文件

确保你的项目使用 Go Modules 进行依赖管理。如果尚未初始化，可以在项目根目录下运行：

go mod init github.com/yourusername/my-gin-app

然后添加依赖：

go get -u github.com/gin-gonic/gin
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/swag/cmd/swag

go.mod 文件示例：

module github.com/yourusername/my-gin-app

go 1.20

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/swaggo/gin-swagger v1.3.0
    github.com/swaggo/swag v1.8.10
)

require (
    // 其他依赖...
)

注意：github.com/yourusername/my-gin-app 替换为你的实际模块路径。

9.3 `main.go` 文件

package main

import (
    "github.com/gin-gonic/gin"
    _ "github.com/swaggo/gin-swagger"                   // 导入 gin-swagger 包
    _ "github.com/swaggo/gin-swagger/swaggerFiles"      // 导入 swaggerFiles 包
    _ "github.com/yourusername/my-gin-app/docs"         // 导入生成的 docs 包（替换为你的模块路径）
    "github.com/yourusername/my-gin-app/handlers"       // 导入 handlers 包
)

// @title My Gin API
// @version 1.0
// @description 这是一个使用 Gin 和 Swagger 的示例 API。
// @host localhost:8080
// @BasePath /
func main() {
    r := gin.Default()

    // 注册 Swagger 路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // 注册 API 路由
    r.GET("/treasures", handlers.GetTreasures)
    r.GET("/treasures/:id", handlers.GetTreasureByID)

    // 启动服务器
    r.Run(":8080")
}

注意：

将 "github.com/yourusername/my-gin-app/docs" 替换为你的实际模块路径。

确保 handlers 包已正确导入，并且处理器函数已定义。

9.4 `handlers/treasure.go` 文件

package handlers

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

// Treasure 结构体定义
type Treasure struct {
    Id         int64 `json:"id"`          // 唯一ID，自增
    UserId     int   `json:"userid"`      // 玩家ID
    TreasureId int   `json:"treasure_id"` // 宝库ID
    Count      int   `json:"count"`       // 数量
    Active     int   `json:"active"`      // 是否已激活
    Level      int   `json:"level"`       // 等级
    StarLv     int   `json:"star_lv"`     // 星级
    ActiveAt   int64 `json:"active_at"`   // 激活时间
    CreatedAt  int64 `json:"created_at"`  // 创建时间
    UpdatedAt  int64 `json:"updated_at"`  // 更新时间
}

// @Summary 获取所有宝藏
// @Description 获取所有宝藏的列表
// @Tags Treasures
// @Accept json
// @Produce json
// @Success 200 {array} Treasure
// @Router /treasures [get]
func GetTreasures(c *gin.Context) {
    // 示例数据，实际应从数据库获取
    treasures := []Treasure{
        {
            Id:         1,
            UserId:     101,
            TreasureId: 1,
            Count:      5,
            Active:     1,
            Level:      3,
            StarLv:     2,
            ActiveAt:   1633072800,
            CreatedAt:  1633072000,
            UpdatedAt:  1633072800,
        },
        {
            Id:         2,
            UserId:     101,
            TreasureId: 2,
            Count:      3,
            Active:     0,
            Level:      2,
            StarLv:     1,
            ActiveAt:   0,
            CreatedAt:  1633072100,
            UpdatedAt:  1633072100,
        },
    }
    c.JSON(http.StatusOK, treasures)
}

// @Summary 获取单个宝藏
// @Description 根据 ID 获取单个宝藏的详细信息
// @Tags Treasures
// @Accept json
// @Produce json
// @Param id path int true "宝藏ID"
// @Success 200 {object} Treasure
// @Failure 404 {object} map[string]string
// @Router /treasures/{id} [get]
func GetTreasureByID(c *gin.Context) {
    id := c.Param("id")
    // 示例数据，实际应从数据库获取
    // 这里简单返回一个示例宝藏，实际应根据 id 查询数据库
    treasure := Treasure{
        Id:         1,
        UserId:     101,
        TreasureId: 1,
        Count:      5,
        Active:     1,
        Level:      3,
        StarLv:     2,
        ActiveAt:   1633072800,
        CreatedAt:  1633072000,
        UpdatedAt:  1633072800,
    }
    c.JSON(http.StatusOK, treasure)
}

注意：

确保处理器函数是导出的（首字母大写），以便在 main.go 中访问。

在实际应用中，应从数据库或其他数据源获取数据，而不是返回硬编码的示例数据。

10. 总结

通过以上步骤，你已经成功地在基于 Gin 框架的 Go Web 应用中集成了 Swagger 文档，并使用 swaggo/gin-swagger 提供了交互式的 API 文档界面。以下是关键步骤的回顾：

安装必要的工具和依赖：
- 安装 Gin 框架。
- 安装 swaggo/gin-swagger 和 swag 工具。
添加 Swagger 注释：
- 在 main.go 中添加项目级别的 Swagger 注释（如 @title, @version 等）。
- 在处理器函数中添加详细的 API 注释（如 @Summary, @Description, @Param, @Success 等）。
生成 Swagger 文档：
- 使用 swag init 命令生成 docs/ 目录及其中的 Swagger 文档文件。
集成 gin-swagger 到 Gin 应用：
- 在 main.go 中导入 gin-swagger 相关包。
- 注册 Swagger 路由 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))。
- 注册你的 API 路由。
访问 Swagger UI：
- 启动 Gin 应用，访问 http://localhost:8080/swagger/index.html 查看和测试 API 文档。
解决常见问题：
- 确保注释格式正确，路径导入正确，swag init 成功执行。
- 确保 API 路由和处理函数正确注册和实现。

通过集成 Swagger 文档，你的 API 变得更加易于理解、测试和维护，同时也提升了开发效率和协作体验。

【声明】本内容来自华为云开发者社区博主，不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源（华为云社区）、文章链接、文章作者等基本信息，否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容，欢迎发送邮件进行举报，并提供相关证据，一经查实，本社区将立刻删除涉嫌侵权内容，举报邮箱： cloudbbs@huaweicloud.com

点赞
收藏
关注作者

0/1000

抱歉，系统识别当前为高风险访问，暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称，即可参与社区互动！

*长度不超过10个汉字或20个英文字符，设置后3个月内不可修改。

确认取消

加入云驻计划，成为创作者

华为云周边好礼
免费体验产品
特殊身份标识
线下官方门票
内部专家零距离
与10000+优质创作者共同成长

立即加入

github.com/swaggo/gin-swagger 如何使用

​​1. 简介​​

​​2. 前提条件​​

​​3. 安装​​

​​3.1 安装 Gin 框架​​

​​3.2 安装 swaggo/gin-swagger​​

​​3.3 安装 swag 工具​​

​​4. 项目结构示例​​

​​5. 使用 swag 生成 Swagger 文档​​

​​5.1 安装 swag 工具​​

​​5.2 添加 Swagger 注释​​

​​5.2.1 在 main.go 中添加注释​​

​​5.2.2 在处理器函数中添加注释​​

​​5.3 生成 Swagger 文档​​

​​5.3.1 在项目根目录执行 swag init​​

​​5.3.2 确保 docs 目录被正确导入​​

​​5.3.3 确保 ginSwagger 能访问文档​​

​​6. 集成 gin-swagger 到 Gin 应用​​

​​6.1 修改 main.go 以注册 Swagger 路由​​

​​6.2 注册 API 路由​​

​​7. 访问 Swagger UI​​

​​7.1 启动 Gin 应用​​

​​7.2 打开浏览器访问 Swagger UI​​

​​8. 常见问题及解决方案​​

​​问题 1：访问 http://localhost:8080/swagger/index.html 显示 404 或空白页面​​

​​问题 2：Swagger UI 显示 API 但无法访问（404 错误）​​

​​问题 3：Swagger UI 中 API 参数或响应不正确​​

​​问题 4：swag init 报错或无法识别注释​​

​​9. 完整示例代码​​

​​9.1 项目结构​​

​​9.2 go.mod 文件​​

​​9.3 main.go 文件​​

​​9.4 handlers/treasure.go 文件​​

​​10. 总结​​

全部回复

设置昵称

关于作者

目录

加入云驻计划，成为创作者

推荐阅读

相关产品

1. 简介

2. 前提条件

3. 安装

3.1 安装 Gin 框架

3.2 安装 `swaggo/gin-swagger`

3.3 安装 `swag` 工具

4. 项目结构示例

5. 使用 `swag` 生成 Swagger 文档

5.1 安装 `swag` 工具

5.2 添加 Swagger 注释

5.2.1 在 `main.go` 中添加注释

5.2.2 在处理器函数中添加注释

5.3 生成 Swagger 文档

5.3.1 在项目根目录执行 `swag init`

5.3.2 确保 `docs` 目录被正确导入

5.3.3 确保 `ginSwagger` 能访问文档

6. 集成 `gin-swagger` 到 Gin 应用

6.1 修改 `main.go` 以注册 Swagger 路由

6.2 注册 API 路由

7. 访问 Swagger UI

7.1 启动 Gin 应用

7.2 打开浏览器访问 Swagger UI

8. 常见问题及解决方案

问题 1：访问 `http://localhost:8080/swagger/index.html` 显示 404 或空白页面

问题 2：Swagger UI 显示 API 但无法访问（404 错误）

问题 3：Swagger UI 中 API 参数或响应不正确

问题 4：`swag init` 报错或无法识别注释

9. 完整示例代码

9.1 项目结构

9.2 `go.mod` 文件

9.3 `main.go` 文件

9.4 `handlers/treasure.go` 文件

10. 总结