Golang gin框架使用swagger生成接囗文档

已于 2023-01-11 16:32:15 修改
阅读量6.2k 收藏 25
点赞数 5
分类专栏： Golang 文章标签： golang
于 2022-04-16 06:00:00 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/ling1998/article/details/124205500
版权

0、开发环境

操作系统：Win10

Golang版本：1.15

1、安装swag

go get github.com/swaggo/swag/cmd/swag

此时会在环境变量 GOBIN目录中生成swag.exe，如下图所示

 验证是否安装成功

F:\Golang\TalentChain\talentchain>swag -v
swag version v1.8.1

若没有生成，则可以使用以下命令：

go install github.com/swaggo/swag/cmd/swag@latest

2、安装依赖包

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

 3、编写注解及添加访问路由

（1）导入包

package main

import (
	//.....省略许多包
	_ "talentchain/docs" //talentchain是工程的module名称，改成自己工程的module名
)

注：必须导入docs，否则将报错： Failed to load API definition. 如下图所示：

（2）编写注解

注：注解详情可参见官网文档 Swagger Documentation

go-swapper注解规范说明

// @Summary 摘要

// @Description 描述

// @Description 接口的详细描述

// @Id 全局标识符

// @Version 接口版本号

// @Tags 接口分组，相当于归类

// @Accept json 浏览器可处理数据类型

// @Produce json 设置返回数据的类型和编码

// @Param 参数格式 从左到右：参数名、入参类型、数据类型、是否必填和注释  例：id query int true "ID"

// @Success 响应成功 从左到右：状态码、参数类型、数据类型和注释  例：200 {string} string "success"

// @Failure 响应失败 从左到右：状态码、参数类型、数据类型和注释  例：400 {object}  string "缺少参数 ID"

// @Router 路由： 地址和http方法  例：/api/user/{id} [get]

// @contact.name 接口联系人

// @contact.url 联系人网址

// @contact.email 联系人邮箱

### 增加token验证方法

// @securityDefinitions.apikey ApiKeyAuth  安全方式

// @in header  token携带的位置，这里是在header中

// @name Authorization  heaer中的名称

参数param的几种类型 

query 形如 /user?userId=1016
body 需要将数据放到 body 中进行请求
formData multipart/form-data* 请求
path 形如 /user/1016
header header头信息

上面对基本注解进行了解释，下面在代码中增加注解 

main函数添加注解 

package main

import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"talentchain/controller"
	_ "talentchain/docs"
)

// @title 接囗文档
// @version 1.0
// @description 上链项目
// @termsofservice https://github.com/xxxx
// @contact.name Tracy
// @contact.email xxxx@126.com
// @host 127.0.0.1:9090
func main() {

	r := gin.Default()

	r.POST("/labourer/register",controller.Register)

	r.Run(":9090")
}

注：main函数中的@host，其他所有路由接囗都默认成此地址，如有特殊可以在路由接囗中添加@host，覆盖main的@host , 不加@host 可以设置成动态的，这样方便部署任何平台，不依赖HOST， 如下所示：

package main

import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"talentchain/controller"
	_ "talentchain/docs"
)

// @title 接囗文档
// @version 1.0
// @description 上链项目
// @termsofservice https://github.com/xxxx
// @contact.name Tracy
// @contact.email xxxx@126.com
func main() {

	r := gin.Default()

	r.POST("/labourer/register",controller.Register)

	r.Run(":9090")
}

 路由函数添加注解

// @Summary 个人注册
// @title Swagger API
// @version 1.0
// @Tags 劳动者管理
// @description  个人注册接囗
// @BasePath /labourer/register
// @Produce  json
// @Param phone body LabourerInfo true "劳动者信息"
// @Success 200 {object} RespData "{"code":200,"data":{},"msg":"ok"}"
// @Router /labourer/register [post]
func Register(c *gin.Context)  {
	// to do something
}

（3）添加访问路由

    # 添加swagger访问路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

package main

import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"talentchain/controller"
	_ "talentchain/docs"
)

// @title 接囗文档
// @version 1.0
// @contact.name Tracy
// @contact.email xxxx@126.com
// @host 127.0.0.1:9090
func main() {

	r := gin.Default()

    // 添加swagger访问路由
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.POST("/labourer/register",controller.Register)

	r.Run(":9090")
}

（4）格式化swag注解

swag fmt

 格式化后注解被美化了

package main

import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"talentchain/controller"
	_ "talentchain/docs"
)

// @title          接囗文档
// @version        1.0
// @contact.name   Tracy
// @contact.email  zhangyanling1998@126.com
// @host           127.0.0.1:9090
func main() {

	r := gin.Default()

    // 添加swagger访问路由
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.POST("/labourer/register",controller.Register)

	r.Run(":9090")
}

4、生成文档

swag init

将会生成一个docs文件夹，下面生成3个文件，如下所示： 

F:\Golang\TalentChain\talentchain>tree /F docs
文件夹 PATH 列表
卷序列号为 00000040 0CA4:1102
F:\GOLANG\TALENTCHAIN\TALENTCHAIN\DOCS
    docs.go
    swagger.json
    swagger.yaml

注：每次添加或修改注解后，都需要使用swag init命令重新生成文档，使其生效

swag init 默认通过项目根目录中的main.go文件生成，如果main.go不在根目录中，如在cmd/main.go中，则要使用参数-g, 命令：

swag init -g ./cmd/main.go

5、浏览器访问

启动工程，在浏览器中输入地址：http://127.0.0.1:9090/swagger/index.html

测试接囗

点击接囗右侧展开按钮

点击"Try it out"按钮

 输入参数值，点击”Execute“按钮

查看响应结果

6、补充

6.1、Token验证

main函数加

// @securityDefinitions.apikey  ApiKeyAuth
// @in                          header
// @name                        Authorization
package main

import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"talentchain/controller"
	_ "talentchain/docs"
)

// @title 接囗文档
// @version 1.0
// @description 上链项目
// @termsofservice https://github.com/xxxx
// @contact.name Tracy
// @contact.email xxxx@126.com
// @securityDefinitions.apikey  ApiKeyAuth
// @in                          header
// @name                        Authorization
func main() {

	r := gin.Default()

	r.POST("/labourer/register",controller.Register)

	r.Run(":9090")
}

路由函数加：

 // @Security ApiKeyAuth

// @Summary 个人注册
// @title Swagger API
// @version 1.0
// @Tags 劳动者管理
// @description  个人注册接囗
// @Security  ApiKeyAuth
// @Produce  json
// @Param phone body LabourerInfo true "劳动者信息"
// @Success 200 {object} RespData "{"code":200,"data":{},"msg":"ok"}"
// @Router /labourer/register [post]
func Register(c *gin.Context)  {
	// to do something
}

6.2、上传文件

 路由函数增加：

// @Accept    multipart/form-data
// @Param     file  formData  file          true  "file"

// @Summary   上传用户头像
// @version  1.0
// @Tags     用户接囗
// @Security  ApiKeyAuth
// @Accept    multipart/form-data
// @Produce  json
// @Param     file  formData  file          true  "file"
// @Success  0       {object}  tools.RespData       "{  "code": 0, "data": "xxx",  "msg": "正常" }"
// @Router    /api/v1/user/avatar [post]
func UploadUserAvatar(context *gin.Context) {

}

参见官网文档 Swagger Documentation

瘦身小蚂蚁
关注
  • 5
    点赞
  • 踩
  • 25
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
gin-swagger:使用 Swagger 2.0 自动生成 RESTful API 文档的 gin 中间件
07-24
大摇大摆的 gin 中间件使用 Swagger 2.0 自动生成 RESTful API 文档。 用法 开始使用它 向您的 API 源代码添加注释，。 使用以下命令下载 for Go： $ go get -u github.com/swaggo/swag/cmd/swag 在包含main.go文件的 Go 项目根文件夹中运行 ， 将解析注释并生成所需文件（ docs文件夹和docs/doc.go ）。 $ swag init 使用以下命令下载 ： $ go get -u github.com/swaggo/gin-swagger $ go get -u github.com/swaggo/files 并在您的代码中导入以下内容： import "github.com/swaggo/gin-swagger" // gin-swagger middleware import "
基于golang的swagger超贴心、超详细使用指南【有很多坑】
热门推荐
【阿冰】
03-09 1万+
Swagger 相关的工具集会根据 OpenAPI 规范去生成各式各类的与接口相关联的内容，常见的流程是编写注解 =》调用生成库-》生成标准描述文件 =》生成/导入到对应的 Swagger 工具。 安装 因此接下来第一步，我们要先安装 Go 对应的开源 Swagger 相关联的库，在项目 blog-service 根目录下执行安装命令，如下： $ go get -u github.com/swaggo/swag/cmd/swag $ go get -u github.com/swaggo/gin-swagg
golang使用swagger
最新发布
lemonth的博客
06-05 246
报错 Fetch error Internal Server Error doc.json是没有引入docs。'swag' 不是内部或外部命令，也不是可运行的程序。需要安装到bin环境变量。
golang 引入swagger（iris、gin）
weixin_45565886的博客
02-06 2569
golang 引入swagger（iris、gin）
Golang使用Swagger文档教程
12-04 1406
其次，想要生成swagger文档也非常简单，然后，为swagger注册gin路由。简单介绍一下Swagger的使用。首先导入swagger相关的包。
golang swagger
qq_36020617的博客
10-22 1567
我看网上很多关于golang gin整合swagger的教程，但都写的比较模糊，所以我自己整理了一个golang引入swagger的教程，希望能帮到大家。
go语言web开发系列之二十七:gin框架:用gin-swagger实现接口文档
刘老师的技术森林
02-03 2992
一，安装用到的库 1，swag库的地址: https://github.com/swaggo/swag 2，安装swag命令: liuhongdi@ku:~$ go get -u github.com/swaggo/swag/cmd/swag 测试安装是否成功? liuhongdi@ku:/data/liuhongdi/digv27$ /home/liuhongdi/go/bin/swag -v swag version v1.6.9 在项目包含main.go文件的目录下执行: liu
golang(gin)整合mysql,整合redis通用脚手架
04-06
8. **API文档**：生成清晰的API文档，可以使用Swagger等工具。 通过以上步骤，你将能够构建一个完整的、集成了Gin、MySQL和Redis的后端应用。这个通用脚手架将为你提供一个坚实的基础，方便后续功能的扩展和维护。...
基于Go Web框架Gin RESTfull接口 Swagger API + Gorm + viper+ Docker
05-23
它使用静态类型系统和编译型语言的优势，能够生成高效的机器码。 并发性：Go语言内置了对并发的支持，通过轻量级的goroutine和channel机制，可以轻松实现并发编程。这使得Go语言在构建高性能的服务器和分布式系统时...
gin-swagger:可旋转的DRY模板
04-12
gin-swagger-用于go-swagger的DRY模板gin-swagger是一个基于协助编写golang REST API的工具。 给定REST API的规范， gin-swagger可以为您生成所有无聊的样板内容，因此您只需要实现API的核心业务逻辑即可。 它基于...
go-todo-app:带有Gin框架的干净架构Todo Restful Api
03-13
技术领域Go Web框架（gin-gonic） 容器化（Docker） 昂首阔步（swaggo） 数据库Mongodb（默认） Redis（很快） 依赖注入（由Google连线） 单元/集成测试（作证） 跟踪（opentrace） WebUI（Angular 11）Web UI预览...
Gin-swagger完整使用教程
joychenwenyu的博客
09-19 4752
golang gin swagger使用教程
GO语言gin框架实战-03-swagger和接口文档
运维玄德公
11-08 1620
1. GET 1.1 query模式 1.2 path 模式 2 POST 2.1 body模式 2.2 formData模式 3. PUT 3.1 body模式 3.2 formData模式 4. DELETE 4.1 query 4.2 Path
Gin-Swagger的使用
qq_51898139的博客
08-22 3773
gin-swagger的使用
Gin框架中配置Swagger（完整流程版）
无言.
05-10 3056
Gin框架中配置Swagger。Swagger是一个API文档工具，可以用于自动生成、描述、调试和可视化RESTful API文档。其通过标准化API的描述格式和工具链，帮助开发者快速创建和部署API。
Go的Gin框架整合Swagger
u013068184的博客
06-11 8081
最近在研究Go的Gin框架，本文简单记录怎么整合Swagger。 版本信息： gin v1.6.3 swag v1.6.7 首先下载安装Gin以及Swagger依赖包： go get -u github.com/gin-gonic/gin go get -u github.com/swaggo/swag/cmd/swag 若报以下错： go get github.com/gin-gonic/gin: module github.com/gin-gonic/gin: Get "https://proxy.
Golang | Web开发之Gin使用swag生成项目的Swagger-API接口文档
WeiyiGeek 唯一极客IT知识分享
06-13 2040
Swagger工具是由原始“Swagger”规范背后的团队开发的。Swagger提供了最强大和最容易使用的工具，以充分利用OpenAPI规范。go-swagger 是一个主要生成或分析源代码的工具，我们可以使用 go-swagger 工具为Gin项目使用Swagger 2.0自动生成RESTful API文档。
Go语言gin框架+gorm框架项目：后端配置swagger
pyscl01的博客
05-08 2032
Go语言gin框架+gorm框架项目：后端配置swagger的详细步骤
golang gin框架 项目实战
05-30
好的，我可以为您提供一些关于使用 Golang Gin 框架进行项目实战的建议。 首先，您需要安装 Golang 和 Gin 框架。安装过程可以参考官方文档进行操作。然后，您可以按照以下步骤进行项目实战： 1. 创建项目结构 在您的 GOPATH 目录下创建一个新的项目文件夹。通常情况下，您需要为项目创建以下子文件夹： ``` . ├── main.go ├── config │ ├── config.go │ └── ... ├── controller │ ├── home_controller.go │ └── ... ├── middleware │ ├── auth.go │ └── ... ├── model │ ├── user.go │ └── ... ├── router │ ├── router.go │ └── ... └── service ├── user_service.go └── ... ``` 2. 创建路由 在 router 文件夹中创建一个 router.go 文件，并编写以下代码： ```go package router import ( "github.com/gin-gonic/gin" "your-project/controller" "your-project/middleware" ) func SetupRouter() *gin.Engine { r := gin.Default() // 中间件 r.Use(middleware.AuthMiddleware()) // 路由 r.GET("/", controller.HomePageHandler) return r } ``` 在上面的代码中，我们使用了 gin 框架中的 gin.Default() 函数来创建一个默认的 gin.Engine 实例，并使用中间件来进行身份验证。然后我们定义了一个路由，将根路径映射到 HomePageHandler 方法。 3. 创建控制器 在 controller 文件夹中创建 home_controller.go 文件，并编写以下代码： ```go package controller import ( "github.com/gin-gonic/gin" "your-project/service" ) func HomePageHandler(c *gin.Context) { users := service.GetAllUsers() c.JSON(200, users) } ``` 在上面的代码中，我们定义了一个 HomePageHandler 方法，它接收一个 gin.Context 对象作为参数，并使用 service 层中的 GetAllUsers 函数获取所有用户的数据。然后我们使用 JSON 方法将数据以 JSON 格式返回给客户端。 4. 创建服务层 在 service 文件夹中创建 user_service.go 文件，并编写以下代码： ```go package service import "your-project/model" func GetAllUsers() []*model.User { // TODO: 查询数据库获取所有用户数据 return []*model.User{} } ``` 在上面的代码中，我们定义了一个 GetAllUsers 函数，它返回一个包含所有用户数据的切片。在实际项目中，我们需要查询数据库来获取这些数据。 5. 创建模型 在 model 文件夹中创建 user.go 文件，并编写以下代码： ```go package model type User struct { ID int `json:"id"` Name string `json:"name"` Age int `json:"age"` } ``` 在上面的代码中，我们定义了一个 User 结构体，它包含三个字段：ID、Name 和 Age。这些字段将用于存储每个用户的信息。 6. 创建配置文件 在 config 文件夹中创建 config.go 文件，并编写以下代码： ```go package config const ( DB_HOST = "localhost" DB_PORT = "3306" DB_USERNAME = "root" DB_PASSWORD = "password" DB_NAME = "your-database-name" ) ``` 在上面的代码中，我们定义了一些常量，用于存储数据库配置信息。这些常量将在连接数据库时使用。 7. 连接数据库 在 service 层中的 GetAllUsers 函数中，我们需要连接数据库来获取所有用户数据。可以使用以下代码来连接 MySQL 数据库： ```go package service import ( "database/sql" "fmt" "your-project/config" "your-project/model" ) func GetAllUsers() []*model.User { // 连接数据库 db, err := sql.Open("mysql", fmt.Sprintf("%s:%s@tcp(%s:%s)/%s", config.DB_USERNAME, config.DB_PASSWORD, config.DB_HOST, config.DB_PORT, config.DB_NAME, )) if err != nil { panic(err) } defer db.Close() // 查询所有用户数据 rows, err := db.Query("SELECT * FROM users") if err != nil { panic(err) } // 解析查询结果 users := []*model.User{} for rows.Next() { user := &model.User{} err := rows.Scan(&user.ID, &user.Name, &user.Age) if err != nil { panic(err) } users = append(users, user) } return users } ``` 在上面的代码中，我们使用 sql.Open 函数来打开 MySQL 数据库连接。然后我们使用 db.Query 函数来查询所有用户数据，并使用 rows.Scan 函数将查询结果解析为 User 结构体的切片。 以上就是使用 Golang Gin 框架进行项目实战的流程。当然，在实际项目中，您需要根据自己的需求进行相应的修改和扩展。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值