Go语言中文网，致力于每日分享编码知识，欢迎关注我，会有意想不到的收获！

一个好的 API's，必然离不开一个好的API文件

要开发纯手写 API 文件，不存在的 :=)

专案地址：https://github.com/EDDYCJY/go-gin-example

安装 swag

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

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

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

2、gopm get

该包有引用golang.org上的包，若无科学上网，你可以使用 gopm 进行安装

gopm get -g -v github.com/swaggo/swag/cmd/swag

cd $GOPATH/src/github.com/swaggo/swag/cmd/swag

go install

同理将其可执行档案移动到$GOBIN下

验证是否安装成功

swag version v1.1.1

安装 gin-swagger

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

注：三个包都有一定大小，安装需要等一会或要科学上网

初始化

Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明档案

gin-swagger 给出的范例：

// @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]

我们可以参照 Swagger 的注解规范和范例去编写

// @Summary 新增文章标签

// @Produce json

// @Param name query string true "Name"

// @Param state query int false "State"

// @Param created_by query int false "CreatedBy"

// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"

// @Router /api/v1/tags [post]

func AddTag(c *gin.Context) {

// @Summary 修改文章标签

// @Produce json

// @Param id path int true "ID"

// @Param name query string true "ID"

// @Param state query int false "State"

// @Param modified_by query string true "ModifiedBy"

// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"

// @Router /api/v1/tags/{id} [put]

func EditTag(c *gin.Context) {

详细的注解请参见 go-gin-example。以确保获取最新的 swag 语法

生成

[$ gin-blog]# swag init

2018/03/13 23:32:10 Generate swagger docs....

2018/03/13 23:32:10 Generate general API Info

2018/03/13 23:32:10 create docs.go at docs/docs.go

完毕后会在专案根目录下生成docs

docs/

├── docs.go

└── swagger

├── swagger.json

└── swagger.yaml

我们可以检查 docs.go 档案中的 doc 变数，详细记载中我们档案中所编写的注解和说明

验证

参考

go-gin-example本系列作者：煎鱼，原创授权释出