安装swag

如果开启了go module,建议不要在项目目录运行安装命令

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

安装完成后运行swag -v,查看版本号输出:swag version v1.X.0则安装成功

安装框架扩展包(以gin为例)

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

初始化文档

swag init

配置文档路由

package main

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

    _ "XXX/docs" // !!!这里导入swag init 生成的包!!!!
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2
func main() {
    r := gin.New()

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

    r.Run()
}

更新文档

再次执行swag init更新文档,运行go run main.go,访问localhost:8080/swagger/index.html即可查看文档

swagger注释文档书写格式:

以下示例中的object均为对应api的请求或响应struct,生成文档时会自动加载。

不带参数和Header的请求

示例接口:http://localhost/api/get
Go-Router:v2.GET("/api/get", api.GetApi)

// @Summary 接口描述
// @Tags 分类名称
// @Accept application/json
// @Success 200 object result.Response 返回值
// @Router /api/get [get]
func GetApi(c *gin.Context) {
    res := service.GetApi()
    c.JSON(200, res)
}

带Url参数请求

示例接口:http://localhost/api/get?userId=123
Go-Router:v2.GET("/api/get", api.GetApi)

// @Summary 接口描述
// @Tags 分类名称
// @Accept application/json
// @Param userId query integer true "用户ID"
// @Success 200 object result.Response 返回值
// @Router /api/get [get]
func GetApi(c *gin.Context) {
    userId:=c.Query("userId") //查询请求URL后面的参数
    res := service.GetApi(userId)
    c.JSON(200, res)
}

带Path参数请求

示例接口:http://localhost/api/get/123
Go-Router:v2.GET("/api/get/:userId", api.GetApi)

// @Summary 接口描述
// @Tags 分类名称
// @Accept application/json
// @Param userId path integer true "用户ID"
// @Success 200 object result.Response 返回值
// @Router /api/get/{userId} [get]
func GetApi(c *gin.Context) {
    userId:=c.Param("userId") //查询路径Path参数
    res := service.GetApi(userId)
    c.JSON(200, res)
}

带Token请求

示例接口:http://localhost/api/get/123
Go-Router:v2.GET("/api/get/:userId", api.GetApi)

// @Summary 接口描述
// @Tags 分类名称
// @Accept application/json
// @Param token header string true "登录信息"
// @Success 200 object result.Response 返回值
// @Router /api/get [get]
func GetApi(c *gin.Context) {
    userId,_ :=c.Get("tokenUserId") //从解析token获取用户Id
    res := service.GetApi(userId)
    c.JSON(200, res)
}

带Body参数跟Token请求

示例接口:http://localhost/api/post
Go-Router:v2.POST("/api/post", api.PostApi)

// @Summary 接口描述
// @Tags 分类名称
// @Accept application/json
// @Param token header string true "登录信息"
// @Param data body service.ReqData true "请求参数结构体"
// @Success 200 object result.Response 返回值
// @Router /api/post [ post ]
func PostApi(c *gin.Context) {
    var req service.ReqData
    err := c.BindJSON(&req)
    if err!=nil{
        c.JSON(200, result.ReturnFailMsg("获取参数失败"))
    }else {
        userId,_ :=c.Get("tokenUserId") //从解析token获取用户Id
        req.UserId = userId
        res := req.PostApi()
        c.JSON(200,res)
    }
}

带文件和Token请求

示例接口:http://localhost/api/file
Go-Router:v2.POST("/api/file", api.PostFile)

// @Summary 接口描述
// @Tags 分类名称
// @Accept application/json
// @Param token header string true "登录信息"
// @Param data formData file true "文件"
// @Success 200 object result.Response 返回值
// @Router /api/file [ post ]
func PostFile(c *gin.Context) {
    file, _ := c.FormFile("file")
    res := req.PostFile(file)
    c.JSON(200,res)
}
参考文章:Golang – Gin & Swaggo 使用方法
Last modification:January 30th, 2021 at 10:46 pm