辉忆年
0%

go添加swag

发表于 更新于 分类于 Valine：

1、查看 path 中是否有 $GOPATH/bin ，没有就加上

2、go get

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

执行成功后，在 $GOPATH/bin 会有一个 swag.exe

swag 命令

1
2
3
4
5
6
7
8
COMMANDS:
   init, i  Create docs.go
   fmt, f   format swag comments
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)

3、工程目录下（即 main.go 的根目录），运行 swag i 。这将会解析注释并生成需要的文件（docs文件夹和docs/docs.go）

目录结构：

  • 工程目录
    • docs
      • docs.go
      • swagger.json
      • swagger.yaml

4、为 swag 添加路由

1
2
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

路由初始化处添加

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

并在该文件引入 docs 文件夹

1
2
3
4
5
import (
	...
	_ "project/docs"
	...
)

5、编写API注释

gin-swagger 中的范例

1
2
3
4
5
6
7
8
9
// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

swag地址

Declarative Comments Format

6、swag i 重新生成docs，运行代码（ gin 运行 端口号 8000）。进入http://localhost:8000/swagger/index.html