介绍:
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:
Go
// @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:
Go
// @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
Go
// @Summary 用户登录
// @Description 用户登录接口,返回用户信息和token
func Login(c *gin.Context) {
// 登录逻辑
}
@Tags
Go
// @Tags auth
@Produce 和 @Consume
Go
// @Produce json
// @Consume json
@Param
Go
// @Param username query string true "用户名"
// @Param password query string true "密码"
@BodyParam
Go
// @Param user body UserLogin true "用户登录信息"
type UserLogin struct {
Username string `json:"username"`
Password string `json:"password"`
}
@Success 和 @Failure
Go
// @Success 200 {string} string "登录成功"
// @Failure 400 {string} string "请求参数错误"
// @Failure 401 {string} string "用户名或密码错误"
// @Failure 500 {string} string "服务器错误"
@SecurityDefinitions 和 @Security
Go
// @SecurityDefinitions ApiKeyAuth ApiKeyAuth "header" "X-API-KEY"
// @Security ApiKeyAuth []
@Deprecated
Go
// @Deprecated 此接口已过时,请使用新接口
@ExternalDocs
Go
// @ExternalDocs 更多信息,请访问
// @ExternalDocs url https://example.com/docs
@OperationID 和 @Schemes
Go
// @OperationID getUserById
// @Schemes http https
@Example
Go
// @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
bash
# 1.17版本之前 安装命令
go get -u github.com/swaggo/swag/cmd/swag
# 1.17+版本直接安装swag 命令
go install github.com/swaggo/swag/cmd/swag@latest
二、初始化
bash
# 安装没有问题会在项目根目录下生成以下目录(docs/doc.go)
swag init
2024/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 入口配置
Go
// main包导入 docs目录,否则访问时会出错,因为有些静态资源都在该包目录下面
_ "your_project_docs目录_path/docs"
4.2 路由层配置
Go
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
Go
package api
import (
_ "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
Go
package models
import "gorm.io/gorm"
// UserLogin 用户模型
type UserLogin struct {
gorm.Model
UserName string `gorm:"unique"`
PasswordDigest string
}
Go
package models
type Token struct {
AccessToken string `json:"access_token"`
TokenType string `json:"token_type"`
ExpiresIn int `json:"expires_in"`
}
routes/routes.go
Go
package routes
import (
"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)) // 开启swag
v1 := 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
Go
package main
import (
_ "gin-mall/docs" //需要导入,否则访问时会出错,因为有些静态资源都在该包目录下面
"gin-mall/routes"
)
func main() {
r := routes.NewRouter()
r.Run(":8080")
}
五、路由函数注释
5.1 入口配置
main包中添加通用的API注释信息
Go
package main
import (
_ "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)