gin使用swagger生成接口文档-golang

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

在前后端分离的项目开发过程中，如果后端同学能够提供一份清晰明了的接口文档，那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的，而且后续接口文档的维护也十分耗费精力。

最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新，而Swagger正是那种能帮我们解决接口文档问题的工具。

这里以gin框架为例，使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档。

官方文档：https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html

使用步骤：

第一步，入口文件注释

在程序入口main函数上以注释的方式写下项目相关介绍信息。

// @title 接口文档
// @version 1.0
// @description syzz-api
func main() {
    
    
	commands.Handle()
}

第二步，接口HandlerFunc注释

// @Summary 会员注册
// @Accept x-www-form-urlencoded
// @Produce application/json
// @Param username body string true "用户名"
// @Param password body string true "密码"
// @Param phone body string true "手机号"
// @Success 0
// @Router /api/register [post]
func Register(c *gin.Context) {
    
    
	// ......
}

// @Summary 修改会员信息
// @Accept x-www-form-urlencoded
// @Produce application/json
// @Param token header string true "token"
// @Param nickname body string true "昵称"
// @Param photoId body string true "头像ID"
// @Success 0
// @Router /api/resetUserInfo [post]
func ResetUserInfo(c *gin.Context) {
    
    
	// ......
}

第三步，生成接口文档

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

// 在 main 函数所在的目录下
swag init -h

// 默认查找 main.go 文件，此处指定 api.go 文件
swag init -g api.go

执行成功会生成 docs 文件夹。

第四步，引入gin-swagger

在定义路由的文件中引入如下包，同时注册swagger api相关路由。

import (
 	_ "syzz-api/app/api/docs"

	gs "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
)

r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

编译执行。

访问地址：http://192.168.2.157:9007/swagger/index.html#/

在这里插入图片描述