swaggo 介绍和使用
介绍
- Swag是一个开源项目，用于web框架下接口调试和文档管理，可以将代码中的接口注释转换为文档格式，并提供界面在线调试接口的功能。
- 项目地址：https://github.com/swaggo/swag
- 目前项目可以支持的web框架
- gin，echo，buffalo，net/http，gorilla/mux，go-chi/chi，flamingo，fiber，atreugo，hertz
- 在线界面调试和文档效果图
使用
-
文档用的测试环境
- go version go1.20.1 linux/amd64
- swag version v1.16.2（测试时尽量更新到最新版本，旧版本有其他bug）
- 更新操作 go get -u github.com/swaggo/swag/cmd/swag@latest
- 示例用到的web框架为gin
-
安装swag
- go install github.com/swaggo/swag/cmd/swag@latest
-
先实现一个简单的web api 计算俩个值的积
-
目录结构 go mod init demo
├── go.mod
├── go.sum
└── main.go -
main.go
package main import ( "github.com/gin-gonic/gin" "net/http" "strconv" ) // HTTPError example type HTTPError struct { Code int `json:"code" example:"400"` Message string `json:"message" example:"status bad request"` } func CalcExample(ctx *gin.Context) { val1, err := strconv.Atoi(ctx.Query("val1")) if err != nil { er := HTTPError{ Code: http.StatusBadRequest, Message: err.Error(), } ctx.JSON(http.StatusBadRequest, er) return } val2, err := strconv.Atoi(ctx.Query("val2")) if err != nil { er := HTTPError{ Code: http.StatusBadRequest, Message: err.Error(), } ctx.JSON(http.StatusBadRequest, er) return } ans := val1 + val2 ctx.String(http.StatusOK, "%d", ans) } func main() { r := gin.Default() api := r.Group("/examples") api.GET("calc", CalcExample) r.Run(":8080") } -
-
对调用api进行注释
// @title Swagger Example API // @version 1.0 // @description This is a sample swap server // CalcExample godoc // // @Summary calc example // @Description plus // @Tags example // @Accept json // @Produce plain // @Param val1 query int true "used for calc" // @Param val2 query int true "used for calc" // @Success 200 {integer} string "answer" // @Failure 400 {string} string "ok" // @Failure 404 {string} string "ok" // @Failure 500 {string} string "ok" // @Router /examples/calc [get] func CalcExample(ctx *gin.Context) { val1, err := strconv.Atoi(ctx.Query("val1")) if err != nil { er := HTTPError{ Code: http.StatusBadRequest, Message: err.Error(), } ctx.JSON(http.StatusBadRequest, er) return } val2, err := strconv.Atoi(ctx.Query("val2")) if err != nil { er := HTTPError{ Code: http.StatusBadRequest, Message: err.Error(), } ctx.JSON(http.StatusBadRequest, er) return } ans := val1 + val2 ctx.String(http.StatusOK, "%d", ans) } -
生成文档目录
swag init -g main.go -o ./docs
# -g 指定main.go文件路径，默认当前路径下查找main.go文件
# -o 指定输出路径，默认为当前路径
- 在项目根目录下执行执行会在当前目录生成docs目录以及目录下相关文件
- ├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── go.sum
└── main.go
- ├── docs
- 在项目中配置gin-swagger插件和调用重定向代码
import(
_ "demo/docs" //swag init -g main.go 生成的目录模块
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger" //适配gin框架插件
)
func main() {
r := gin.Default()
api := r.Group("/examples")
api.POST("calc", CalcExample)
//重定向接口 usr = basePath + @Router 拼接而成
docs.SwaggerInfo.BasePath = "/"
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run(":8080")
}
- 执行并打开界面进行测试
- go run main.go
- 打开界面进行调试 http://localhost:8080/swagger/index.html
注释规则
-
主要常用注释关键字
- @title 应用程序名（这里官方文档描述必填选项， 实测去掉也行)
- @version api版本号(这里官方文档描述必填选项， 实测去掉也行)
- @Summary 接口概述
- @Description 接口的详细描述
- @Tags 接口类型标记，用来管理界面显示接口，用来进行分类
- @Param 参数说明格式： param name
,param type,data type,is mandatory?,comment - @Success 以空格分隔的成功响应。
return code,{param type},data type,comment - @Router url请求地址 [get/post/或其他方法]
-
更多的注释格式说明