19、Go Gin框架集成Swagger

介绍：

Swagger 支持在 Gin 路由中使用一系列注释来描述 API 的各个方面。以下是一些常用的 Swagger 注释属性，这些属性可以在 Gin 路由的注释中使用：

1. @Summary: 路由的简短摘要。
2. @Description: 路由的详细描述。
3. @Tags: 用于对路由进行分类的标签列表，通常用于生成文档时的分组。
4. @Produce: 描述路由可以返回的 MIME 类型。
5. @Consume: 描述路由可以接受的 MIME 类型。
6. @Param: 描述路由参数的详细信息，包括名称、类型、来源（如 query, path, header, body 等）和描述。
7. @pathParam - 描述路径参数。
8. @headerParam - 描述 HTTP 头参数。
9. @queryParam - 描述查询参数。
10. @BodyParam: 特别用于描述请求体参数的结构和属性。
11. @Success: 描述路由成功时的响应，包括 HTTP 状态码、返回类型和描述。
12. @Failure: 描述路由失败时的响应，包括 HTTP 状态码和描述。
13. @Response: 用于定义单个响应，通常与 @Success 或 @Failure 结合使用。
14. @responses - 描述路由可能返回的各种 HTTP 状态码和相关描述。
15. @responseSchema - 描述响应的 schema，即响应数据的结构。
16. @SecurityDefinitions: 定义全局安全方案。
17. @Security: 应用安全方案到具体的操作。
18. @Deprecated: 标记一个路由或API已经过时。
19. @ExternalDocs: 提供指向外部文档的链接。
20. @OperationID: 为路由提供一个唯一的标识符。
21. @Schemes: 定义API支持的传输协议。
22. @Example: 提供响应示例。
23. @Router：路由路径 [绑定方法] - 指定路由的路径和绑定的 HTTP 方法。（// @Router /users/{id} [get]）

eg:

// @Summary 用户登录
// @Description 用户登录接口
// @Tags auth
// @Produce json
// @Param data body UserLogin true "登录信息"
// @Success 200 {string} string "登录成功"
// @Failure 400 {string} string "请求参数错误"
// @Failure 500 {string} string "服务器错误"
// @Router /api/v1/login [post]
func Login(c *gin.Context) {// 路由处理逻辑
}

在这个例子中，UserLogin 是一个结构体，用于定义 data 参数的结构。@Param 注释中的 true 表示 data 是必须的。 

eg:

// @Summary 用户登录
// @Description 用户登录接口，返回用户信息和token
// @Tags auth
// @Accept json
// @Produce json
// @Param user body UserLogin true "用户登录信息"
// @Success 200 {object} models.Token "成功返回token"
// @Failure 400 {string} string "请求参数错误"
// @Failure 401 {string} string "用户名或密码错误"
// @Failure 500 {string} string "服务器错误"
// @Security ApiKeyAuth
// @Router /api/v1/login [post]
func Login(c *gin.Context) {// 路由处理逻辑
}

在这个例子中，UserLogin 是一个结构体，用于定义请求体中的数据。@Security ApiKeyAuth 表示这个路由需要使用 API 密钥进行认证。 

@Summary 和 @Description

// @Summary 用户登录
// @Description 用户登录接口，返回用户信息和token
func Login(c *gin.Context) {// 登录逻辑
}

@Tags

// @Tags auth

@Produce 和 @Consume

// @Produce json
// @Consume json

@Param

// @Param username query string true "用户名"
// @Param password query string true "密码"

@BodyParam

// @Param user body UserLogin true "用户登录信息"
type UserLogin struct {Username string `json:"username"`Password string `json:"password"`
}

@Success 和 @Failure

// @Success 200 {string} string "登录成功"
// @Failure 400 {string} string "请求参数错误"
// @Failure 401 {string} string "用户名或密码错误"
// @Failure 500 {string} string "服务器错误"

@SecurityDefinitions 和 @Security

// @SecurityDefinitions ApiKeyAuth ApiKeyAuth "header" "X-API-KEY"
// @Security ApiKeyAuth []

@Deprecated

// @Deprecated 此接口已过时，请使用新接口

@ExternalDocs

// @ExternalDocs 更多信息，请访问
// @ExternalDocs url https://example.com/docs

@OperationID 和 @Schemes

// @OperationID getUserById
// @Schemes http https

@Example

// @Example [{ "username": "admin", "password": "admin123" }]

注意事项

• 注释以// @开头，后跟具体的Swagger属性。
• 确保你的结构体（如User和ErrorResponse）在Swagger注释中正确引用，以便它们可以出现在生成的文档中。
• 使用swag init命令可以生成Swagger文档，这通常作为构建步骤的一部分来完成。
• 注释属性需要与 Go 语言的注释语法结合使用，并且通常写在 Gin 路由处理函数的上方。使用 swag init 命令生成 Swagger 文档时，这些注释会被解析并用于构建 API 文档。

在实际使用中，应参考 swaggo/swag 或你所使用的 Swagger 库的官方文档，以确保注释的正确使用和最新的最佳实践。

一、安装

官方地址: https://github.com/swaggo/gin-swagger

# 1.17版本之前 安装命令
go get -u github.com/swaggo/swag/cmd/swag
# 1.17+版本直接安装swag 命令
go install github.com/swaggo/swag/cmd/swag@latest

二、初始化

# 安装没有问题会在项目根目录下生成以下目录(docs/doc.go)
swag init2024/06/06 10:32:59 Generate swagger docs....
2024/06/06 10:32:59 Generate general API Info, search dir:./
2024/06/06 10:32:59 create docs.go at docs/docs.go
2024/06/06 10:32:59 create swagger.json at docs/swagger.json
2024/06/06 10:32:59 create swagger.yaml at docs/swagger.yaml

 

三、安装gin-swagger

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

四、配置

4.1 入口配置

// main包导入 docs目录,否则访问时会出错，因为有些静态资源都在该包目录下面
_ "your_project_docs目录_path/docs"

4.2 路由层配置

import (swaggerFiles "github.com/swaggo/files"ginSwagger "github.com/swaggo/gin-swagger"
)

4.3 访问配置

需要把swagger相关通过路由暴露出去，这样可以直接访问

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

完整示例:

目录结构

api/login.go

package apiimport (_ "gin-mall/models""github.com/gin-gonic/gin"
)// @Summary 用户登录
// @Description 用户登录接口，返回用户信息和token
// @Tags sph
// @Accept json
// @Produce json
// @Param user body models.UserLogin true "用户登录信息"
// @Success 200 {object} models.Token "成功返回token"
// @Failure 400 {string} string "请求参数错误"
// @Failure 401 {string} string "用户名或密码错误"
// @Failure 500 {string} string "服务器错误"
// @Security ApiKeyAuth
// @Router /api/v1/user/login [post]
func Login(c *gin.Context) {c.JSON(200, "登录成功")
}

 需要引入models包，因为用到UserLogin、Token，否则执行swag init时会提示错误

models/user.go、token.go

package modelsimport "gorm.io/gorm"// UserLogin 用户模型
type UserLogin struct {gorm.ModelUserName       string `gorm:"unique"`PasswordDigest string
}

package modelstype Token struct {AccessToken string `json:"access_token"`TokenType   string `json:"token_type"`ExpiresIn   int    `json:"expires_in"`
}

 routes/routes.go

package routesimport ("gin-mall/api"//_ "gin-mall/docs" // 这里需要引入本地已生成文档"github.com/gin-gonic/gin"swaggerFiles "github.com/swaggo/files"ginSwagger "github.com/swaggo/gin-swagger"
)// 路由配置
func NewRouter() *gin.Engine {r := gin.Default()                                                   //生成了一个WSGI应用程序实例r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) // 开启swagv1 := r.Group("api/v1"){v1.GET("ping", func(c *gin.Context) {c.JSON(200, "success")})// 用户操作v1.POST("user/login", api.Login)}return r
}

 main.go

package mainimport (_ "gin-mall/docs" //需要导入，否则访问时会出错，因为有些静态资源都在该包目录下面"gin-mall/routes"
)func main() {r := routes.NewRouter()r.Run(":8080")
}

五、路由函数注释

5.1 入口配置

main包中添加通用的API注释信息

package mainimport (_ "gin-mall/docs" //需要导入，否则访问时会出错，因为有些静态资源都在该包目录下面"gin-mall/routes"
)// @title sph-swagger初识
// @version v0.1
// @description http://127.0.0.1:8080/
// @BasePath /
func main() {r := routes.NewRouter()r.Run(":8080")
}

 

注意: _ "your_project_docs目录_path/docs" 需要导入，否则访问时会出错，因为有些静态资源都在该包目录下面

5.2 初始化注释内容

每次修改都需要执行改操作才能生效

swag init

5.3 项目启动访问

浏览器直接访问项目+swagger路由：http://localhost:8080/swagger/index.html

​

请求参数

​

5.4 更多参考

更多注释请参考官方文档(opens new window)