Go-Gin 框架使用 Swagger 生成 API 文档

Go-Gin 框架使用 Swagger 生成 API 文档

一、前言

在Go语言中，Gin框架因其高效和灵活性广受开发者喜爱。在前后端开发中，一份清晰明了的接口文档能够极大地提高双方的沟通效率和开发效率。结合Swagger生成接口文档，可以帮助开发者更方便地管理和理解API。

Swagger介绍

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

在前后端分离的项目开发过程中，如果后端同学能够提供一份清晰明了的接口文档，那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的，而且后续接口文档的维护也十分耗费精力。

最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新，而Swagger正是那种能帮我们解决接口文档问题的工具。

这里以gin框架为例，使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档。

二、安装 Swagger

（1）全局安装swag CLI

swag是 Swagger 的命令行工具，用于生成 API 文档。可以通过以下命令进行全局安装

1
2
3
$ go get github.com/swaggo/swag/cmd/swag@latest
# 1.16 及以上版本
$ go install github.com/swaggo/swag/cmd/swag@latest
  • go get会拉取指定的包，并将其安装到本地的GOPATH/pkg（Go 1.16 之前）或GOCACHE/pkg/mod（Go 1.16 及之后）目录中
  • go install会将指定的包编译成可执行文件，并安装到GOPATH/bin（Go 1.16 之前）或$HOME/go/bin（Go 1.16 及之后）（不过我的GOPATH/bin其实和$HOME/go/bin路径是一样的，没影响）

（2）项目依赖安装

在项目中需要安装以下依赖以支持 Gin 和 Swagger 的集成：

1
2
3
$ go get github.com/swaggo/gin-swagger
$ go get github.com/swaggo/files
$ go get github.com/alecthomas/template
  • swaggo/files：github.com/swaggo/files 是一个与 swaggo相关的 Go 语言包，用于提供 Swagger 文档的静态文件支持。
  • gin-swagger：Swagger和Gin整合的库。

（3）格式化 Swagger 注释

使用 swag fmt 命令可以格式化项目中的 Swagger 注释，确保注释符合规范：

1
swag fmt

（4）使用 swag CLI 生成文档

运行以下命令生成 Swagger 文档（默认生成 docs.go、swagger.json 和 swagger.yaml 文件）：

1
swag init

swag init 默认会找当前目录下的 main.go 文件，如果不叫 main.go 也可以手动指定文件位置。

1
2
# -o 指定输出目录。
swag init -g cmd/api/api.go -o cmd/api/docs

需要注意的是：swag init 的时候需要在项目根目录下执行，否则无法检测到所有文件中的注释。

比如在 /xxx 目录下执行 swag init 就只能检测到 xxx 目录下的，如果还有和 xxx 目录同级或者更上层的目录中的代码都检测不到。

swag init 常用选项

选项 说明 默认值
--generalInfo, -g 指定包含通用 API 信息的 Go 文件路径 main.go
--dir, -d 指定解析的目录 ./
--exclude 排除解析的目录（多个目录用逗号分隔） 空
--propertyStrategy, -p 结构体字段命名规则（snakecase、camelcase、pascalcase） camelcase
--output, -o 输出文件目录（swagger.json、swagger.yaml 和 docs.go） ./docs
--parseVendor 是否解析 vendor 目录中的 Go 文件 否
--parseDependency 是否解析依赖目录中的 Go 文件 否
--parseInternal 是否解析 internal 包中的 Go 文件 否
--instanceName 设置文档实例名称 swagger

示例：

1
swag init --dir ./ --output ./docs --propertyStrategy snakecase

init 之后会生成一个 docs 文件夹，这里面就是接口描述文件，生成后还需要将其导入到 main.go 中。

在 main.go 中导入刚才生成的 docs 包

加上之前导入的 gin-swag 相关的两个包，一共新导入了三个包。

1
2
3
4
5
import (
	_ "swagger/docs" // main 文件中导入 docs 包
	ginSwagger "github.com/swaggo/gin-swagger"
	swaggerFiles "github.com/swaggo/files"
)

最后则是在 router 中增加 swagger 的 handler 了。

在 main.go 或其他地方增加一个 handler。

1
2
r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

项目运行起来后访问 ip:port/swagger/index.html 即可看到 API 文档。

如果注释有更新，需要重新生成 docs 并重启服务才会生效。

三、Gin-Swagger 实际运用

想要使用gin-swagger为你的代码自动生成接口文档，一般需要下面三个步骤：

  1. 按照swagger要求给接口代码添加声明式注释，具体参照声明式注释格式。
  2. 使用swag工具扫描代码自动生成API接口文档数据
  3. 使用gin-swagger渲染在线接口文档页面

（1）添加注释

通用 API 信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package main

// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService http://swagger.io/terms/

// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 这里写接口服务的host
// @BasePath 这里写base path
func main() {
	r := gin.New()

	r.Run()
}

API 路由注释

在具体路由处理函数上方添加注释，定义该接口的行为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// GetPostById 接口（函数）名称
// @Summary 获取文章信息
// @Description 接口描述
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param id path string true "文章ID"
// @Security ApiKeyAuth
// @Success 200 {object} Post "成功返回文章信息"
// @Failure 400 {string} string "请求参数错误"
// @Router /post/{id} [get]
func GetPostById(c *gin.Context) {
    // 函数实现
}

关键注释字段详解

  • 1. 元数据

    • @Summary：接口的简短描述（单行）。
    • @Description：详细描述（支持多行）。
    • @Tags：接口所属分组（多个标签用逗号分隔）。

    2. 请求与响应

    • @Accept：支持的请求格式（如 application/json, multipart/form-data）。

    • @Produce：返回的响应格式（同上）。

    • @Param：请求参数定义，格式：

      1
      @Param 名称 位置 类型 是否必填 "描述" [额外选项]

      • 位置：path（路径参数）、query（查询参数）、header（请求头）、body（请求体）、formData（表单数据）。

      • 类型：基本类型（string, int, bool 等）或结构体（如 models.User）。

      • 示例：

        1
        2
        3
        @Param token header string true "认证令牌"
        @Param user body models.User true "用户信息"
        @Param page query int false "页码" default(1)

    3. 响应状态码

    • @Success和@Failure：定义不同状态码的响应格式，格式：

      1
      @Success 状态码 {类型} 数据结构 "描述"

      • 类型：

        • {object}：返回对象（如 models.Post）。
        • {array}：返回数组（如 {array} []models.Post）。
        • {string}：返回字符串（如错误信息）。

      • 示例：

        1
        2
        @Success 200 {object} models.Post "成功返回文章"
        @Failure 404 {string} string "文章不存在"

    4. 认证与路由

    • @Security：指定认证方式（需配合全局定义）。

      1
      2
      3
      4
      // 在 main.go 中全局定义 Security 方案
      // @SecurityDefinitions.apikey ApiKeyAuth
      // @In header
      // @Name Authorization

    • @Router：定义路由路径和 HTTP 方法，格式：

      1
      @Router 路径 [方法]
      • 方法：get, post, put, delete, patch 等。

（2）生成接口文档

在项目根目录执行以下命令，使用swag工具生成接口文档数据。

1
swag init

PS：可以多次运行 swag init 命令。每次执行该命令时，swag 工具会重新解析你的代码注释，并更新生成的 Swagger 文档（通常是 docs 目录下的 docs.go 和 swagger.json/yaml 文件）。

执行完上述命令后，如果你写的注释格式没问题，此时你的项目根目录下会多出一个docs文件夹。

1
2
3
4
./docs
├── docs.go
├── swagger.json
└── swagger.yaml

（3）访问文档

启动项目，如果配置了 air 热重载工具直接运行命令air

若没有就直接go run运行

在浏览器中访问http://localhost:8080/swagger/index.html，即可查看交互式 API 文档。

参考博客

golang gin框架使用swagger生成接口文档 - 牛奔 - 博客园

使用 Swagger 为 Go 项目生成 API 文档-腾讯云开发者社区-腾讯云

Go语言 Gin框架整合 Swagger接口文档_go gin swagger-CSDN博客

Go-Gin 框架使用 Swagger 生成 API 文档
http://example.com/2025/07/10/Go-Gin-框架使用-Swagger-生成-API-文档/
作者
yuhua
发布于
2025年7月10日
许可协议