如何使用 go-swagger 文档

发布于 更新于 评论

安装

在Linux下安装的流程

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

若 $GOROOT/bin 没有加入 $PATH 中，你需要执行将其可执行文件移动到 $GOBIN 下

1
mv $GOPATH/bin/swag /usr/local/go/bin

验证是否安装成功

1
2
$ swag -v
swag version v1.1.1

windows下的使用

1
$ go install github.com/swaggo/swag/cmd/swag@latest

安装成功后会生成 swag.exe 到 gopath 的主目录下。

验证是否安装成功

1
2
$ swag -v
swag.exe version v1.8.9

使用

使用 gin-swagger 为你的代码自动生成接口文档，一般需要下面三个步骤：

  1. 按照 swagger 要求给接口代码添加声明式注释。
  2. 使用 swag 工具扫描代码自动生成 api 接口文档数据。
  3. 使用 gin-swagger 渲染在线接口文档页面。

在项目中安装 gin-swagger 扩展

1
2
3
$ go get -u -v github.com/swaggo/gin-swagger
$ go get -u -v github.com/swaggo/files
$ go get -u -v github.com/alecthomas/template

在 main 函数上添加注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// @title Swagger Example API
// @version 1.0
// @description This is a sample server celler server.
// @termsOfService https://razeen.me

// @contact.name Razeen
// @contact.url https://razeen.me
// @contact.email me@razeen.me

// @tag.name TestTag1
// @tag.description	This is a test tag
// @tag.docs.url https://razeen.me
// @tag.docs.description This is my blog site

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

// @host 127.0.0.1:8080
// @BasePath /api/v1

// @schemes http https
// @x-example-key {"key": "value"}

// @description.markdown

添加 swag 路由

1
2
3
4
5
6
7
8
9
10
11
12
import (
	"github.com/gin-gonic/gin"
	"github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "package/docs" // 千万不要忘了导入生成的docs(在下一步中生成)
)

func main()  {
	r := gin.Default()
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.Run(":8088")
}

生成接口文档数据

在项目根目录执行以下命令，使用 swag 工具生成接口文档数据。

1
swag init main.go

执行完上述命令后，如果你写的注释格式没问题，此时你的项目根目录下会多出一个 docs 文件夹。

添加注释

go-swapper注解规范说明：

注：注解详情可参见官网文档 Swagger Documentation

注解描述
@Summary摘要
@ProduceAPI 可以产生的 MIME 类型的列表，MIME 类型你可以简单的理解为响应类型，例如：json、xml、html 等等
@Param参数格式，从左到右分别为：参数名、入参类型、数据类型、是否必填、注释
@Success响应成功，从左到右分别为：状态码、参数类型、数据类型、注释
@Failure响应失败，从左到右分别为：状态码、参数类型、数据类型、注释
@Router路由，从左到右分别为：路由地址，HTTP 方法

Demo

1
2
3
4
5
6
7
8
9
10
11
// @Summary 获取单个文章
// @Produce json
// @Param id path int true "文章ID"
// @Param name query string false "文章名称"
// @Success 200 {object} string "成功"
// @Failure 400 {object} string "请求错误"
// @Failure 500 {object} string "内部错误"
// @Router /api/v1/articles/{id} [get]
func (a Article) Get(c *gin.Context) {

}

格式化 swag 注解

1
swag fmt

启动项目

在浏览器中输入地址：http://127.0.0.1:8088/swagger/index.html 即可看到文档页面

支持框架

  • gin
  • echo
  • buffalo
  • net/http
  • net/http
  • gorilla/mux
  • go-chi/chi
  • flamingo
  • fiber
  • atreugo
  • hertz

将 swagger 文档打包成可执行文件

创建一个文档文件 swag_main.go

1
2
3
4
5
6
7
8
9
10
11
12
package main

import (
    ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    _ "package/docs"
)


func init() {
    swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)
}

执行打包命令：

1
go build -o swag_docs swag_main.go

打包成功后直接运行 swag_docs.exe 即可看到文档页面。

参考资料

swagger 官网

github