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)

相关推荐
hopetomorrow9 分钟前
学习路之PHP--使用GROUP BY 发生错误 SELECT list is not in GROUP BY clause .......... 解决
开发语言·学习·php
小牛itbull19 分钟前
ReactPress vs VuePress vs WordPress
开发语言·javascript·reactpress
请叫我欧皇i27 分钟前
html本地离线引入vant和vue2(详细步骤)
开发语言·前端·javascript
闲暇部落30 分钟前
‌Kotlin中的?.和!!主要区别
android·开发语言·kotlin
GIS瞧葩菜39 分钟前
局部修改3dtiles子模型的位置。
开发语言·javascript·ecmascript
chnming198744 分钟前
STL关联式容器之set
开发语言·c++
熬夜学编程的小王1 小时前
【C++篇】深度解析 C++ List 容器:底层设计与实现揭秘
开发语言·数据结构·c++·stl·list
GIS 数据栈1 小时前
每日一书 《基于ArcGIS的Python编程秘笈》
开发语言·python·arcgis
Mr.131 小时前
什么是 C++ 中的初始化列表?它的作用是什么?初始化列表和在构造函数体内赋值有什么区别?
开发语言·c++
陌小呆^O^1 小时前
Cmakelist.txt之win-c-udp-server
c语言·开发语言·udp