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:

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属性。
  • 确保你的结构体(如UserErrorResponse)在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)

相关推荐
逊嘘8 分钟前
【Java语言】抽象类与接口
java·开发语言·jvm
Half-up11 分钟前
C语言心型代码解析
c语言·开发语言
Source.Liu32 分钟前
【用Rust写CAD】第二章 第四节 函数
开发语言·rust
monkey_meng33 分钟前
【Rust中的迭代器】
开发语言·后端·rust
余衫马36 分钟前
Rust-Trait 特征编程
开发语言·后端·rust
monkey_meng39 分钟前
【Rust中多线程同步机制】
开发语言·redis·后端·rust
Jacob程序员41 分钟前
java导出word文件(手绘)
java·开发语言·word
小白学大数据1 小时前
正则表达式在Kotlin中的应用:提取图片链接
开发语言·python·selenium·正则表达式·kotlin
VBA63371 小时前
VBA之Word应用第三章第三节:打开文档,并将文档分配给变量
开发语言
半盏茶香1 小时前
【C语言】分支和循环详解(下)猜数字游戏
c语言·开发语言·c++·算法·游戏