本文主要是介绍19、Go Gin框架集成Swagger，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！
介绍：
Swagger 支持在 Gin 路由中使用一系列注释来描述 API 的各个方面。以下是一些常用的 Swagger 注释属性，这些属性可以在 Gin 路由的注释中使用：
- @Summary: 路由的简短摘要。
- @Description: 路由的详细描述。
- @Tags: 用于对路由进行分类的标签列表，通常用于生成文档时的分组。
- @Produce: 描述路由可以返回的 MIME 类型。
- @Consume: 描述路由可以接受的 MIME 类型。
- @Param: 描述路由参数的详细信息，包括名称、类型、来源（如 query, path, header, body 等）和描述。
- @pathParam - 描述路径参数。
- @headerParam - 描述 HTTP 头参数。
- @queryParam - 描述查询参数。
- @BodyParam: 特别用于描述请求体参数的结构和属性。
- @Success: 描述路由成功时的响应，包括 HTTP 状态码、返回类型和描述。
- @Failure: 描述路由失败时的响应，包括 HTTP 状态码和描述。
- @Response: 用于定义单个响应，通常与
@Success或@Failure结合使用。 - @responses - 描述路由可能返回的各种 HTTP 状态码和相关描述。
- @responseSchema - 描述响应的 schema，即响应数据的结构。
- @SecurityDefinitions: 定义全局安全方案。
- @Security: 应用安全方案到具体的操作。
- @Deprecated: 标记一个路由或API已经过时。
- @ExternalDocs: 提供指向外部文档的链接。
- @OperationID: 为路由提供一个唯一的标识符。
- @Schemes: 定义API支持的传输协议。
- @Example: 提供响应示例。
- @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)
这篇关于19、Go Gin框架集成Swagger的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！
