swag api接口文档

安装步骤

下载swag

go install github.com/swaggo/swag/cmd/swag@v1.8.12

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

配置路由

package routers

import (
  "github.com/gin-gonic/gin"
  swaggerFiles "github.com/swaggo/files"
  gs "github.com/swaggo/gin-swagger"
)

type RouterGroup struct {
  *gin.RouterGroup
}

func Routers() *gin.Engine {
  router := gin.Default()
  router.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
  // 自己的其他路由
  return router
}

配置一些主要的参数

package main

import (
  "gvd_server/core"
  _ "gvd_server/docs"
  "gvd_server/flags"
  "gvd_server/global"
  "gvd_server/routers"
)

// @title 文档项目api文档
// @version 1.0
// @description API文档
// @host 127.0.0.1:8082
// @BasePath /
func main() {
  global.Log = core.InitLogger()
  global.Config = core.InitConfig()
  global.DB = core.InitMysql()
  global.Redis = core.InitRedis(0)

  option := flags.Parse()
  if option.Run() {
    return
  }

  router := routers.Routers()
  addr := global.Config.System.Addr()
  router.Run(addr)
}

生成api文档

每次接口参数变动，都需要重新执行生成api文档的命令

swag init

访问文档地址

http://127.0.0.1:8082/swagger/index.html

接口文档编写示例

以用户管理为例

创建用户

// UserCreateView 创建用户
// @Tags 用户管理
// @Summary 创建用户
// @Description 创建用户，只能管理员创建
// @Param data body UserCreateRequest true "参数"
// @Param token header string true "token"
// @Router /api/users [post]
// @Produce json
// @Success 200 {object} res.Response{}

用户列表

// UserListView 用户列表
// @Tags 用户管理
// @Summary 用户列表
// @Description 用户列表
// @Param data query models.Pagination true "参数"
// @Param token header string true "token"
// @Router /api/users [get]
// @Produce json
// @Success 200 {object} res.Response{data=res.ListResponse[models.UserModel]}

path参数

// @Param id path int true "id"
// @Router /api/users/{id} [get]

文件上传

// @Accept multipart/form-data
// @Param image formData file true "文件上传"