gin + swagger 生成api接口文档及错误处理

gin + swagger 生成api接口文档

使用go命令，安装swagger工具，会生成swag的二进制文件

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

导入gin依赖包和swagger依赖包

import(
	"net/http" 
	// 这个包下有许多http相关的状态码常量，
	// 可以根据自身的需要导入
	
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
)

执行项目，然后访问swagger生成的api


package main

import (
	
	"github.com/gin-gonic/gin"
	"github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"net/http"
)

// @title 测试
// @version 0.0.1
// @description  测试
// @BasePath /api/v1/
func main() {
	r := gin.New()

	// 创建路由组
	v1 := r.Group("/api/v1")
	
	// curl  http://127.0.0.1:8080/api/v1/test/1
	v1.GET("/test/:id",TestFunc)

	// 文档界面访问URL
	// http://127.0.0.1:8080/swagger/index.html
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	r.Run()
}
// 
// @获取指定ID记录
// @Description 这是controller的功能描述
// @Accept  json
// @Produce json
// @Param   id     path    int     true   "Id"
// @Router /record/{id} [get]
// @Success 200 {string} string	"ok"
func TestFunc(c *gin.Context) {
	c.String(http.StatusOK, "ok")
}

api访问错误，这是因为我们少执行了一步，执行以下的方法

cd project #到项目的目录下
# 执行swag 命令
swag init
2021/12/20 17:04:30 Generate swagger docs....
2021/12/20 17:04:30 Generate general API Info, search dir:./
2021/12/20 17:04:31 create docs.go at docs/docs.go
2021/12/20 17:04:31 create swagger.json at docs/swagger.json
2021/12/20 17:04:31 create swagger.yaml at docs/swagger.yaml
# 会在项目的根目录下生成docs文件夹。然后把docs文件夹导入到项目中

导入docs文件夹,tips:如果使用了mod，前缀一定要添加mod模块名称，例如：_ "github.com/xxx/docs"

import (
	_ "./docs"
	// 导包的时候注意,我的案例是跑在gopath下
	"github.com/gin-gonic/gin"
	"github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	"net/http"
)

现在再去访问http://127.0.0.1:8080/swagger/index.html，应该是ok的

tips:

修改完swag标签后需要重新调用 swag init 命令
swagger标签需要和controller紧挨着，中间不能有空行，不然接口还是有错误
swagger 的标签还可以显示需要校验的信息

// @Summary 获取多个标签

// @Tags 标签

// @Produce  json

// @Param name query string false "标签名称" maxlength(100)

// @Param state query int false "状态" Enums(0, 1) default(1)

// @Param name body string true "标签名称" minlength(3) maxlength(100)

// @Param state body int false "状态" Enums(0, 1) default(1)

// @Param created_by body string false "创建者" minlength(3) maxlength(100)

// @Param page query int false "页码"

// @Param page_size query int false "每页数量"

// @Success 200 {object} model.TagSwagger "成功"

// @Failure 400 {object} errcode.Error "请求错误"

// @Failure 500 {object} errcode.Error "内部错误"

// @Router /api/v1/tags [get]

__EOF__

本文作者：从零单排
本文链接：https://www.cnblogs.com/baixiaoyong/p/16051136.html
关于博主：评论和私信会在第一时间回复。或者直接私信我。
版权声明：本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！
声援博主：如果您觉得文章对您有帮助，可以点击文章右下角【推荐】一下。您的鼓励是博主的最大动力！