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 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 入口配置

// 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 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

package models

import "gorm.io/gorm"

// UserLogin 用户模型
type UserLogin struct {
	gorm.Model
	UserName       string `gorm:"unique"`
	PasswordDigest string
}

package models

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

routes/routes.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

package main

import (
	_ "gin-mall/docs" //需要导入，否则访问时会出错，因为有些静态资源都在该包目录下面
	"gin-mall/routes"
)

func main() {
	r := routes.NewRouter()
	r.Run(":8080")
}

五、路由函数注释

5.1 入口配置

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

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")
}