swag使用

[toc]

Java使用Spring Boot写Restful API时,可以在代码里用注解来标识API,编译为Jar包后,运行时Web应用可以直接托管API文档。具体的可以参考文章:使用swagger来做API文档。

那么golang系有没有类似的做法呢?

有是有的,只是没有springfox的那么方便就是了。

swaggo提供了golang版本的swagger自动生产Restful API文档,其做法是在代码中按swaggo的格式编写api的注释,然后swaggo会去解析这些注释,生成swagger的文档以及托管到网络的框架代码(主要是init()函数),最终将代码编译到网络应用中,达到api文档托管的目的。

由于我的Restful框架用的是gin,所以下面以gin-swagger为例,说明swaggo的用法。

安装swag命令行

要使用swaggo,首先要下载一个swag命令行。

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

在$ GOPATH / bin /下会看到多了一个swag。把$ GOPATH / bin /加到PATH后,就可以直接用swag命令行了。

在包含main.go的Go工程的根目录下执行swag init,swag会检索当前工程里的swag注解(类似上述Java中的注解),生成docs.go以及swagger.json/yaml

获取gin专用的gin-swagger

里面包含了一个示例代码。

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

编写gin-swagger需要的注释

接下来就是编写注释了。注释分为两部分,一是整体应用的说明,二是具体api的说明。

整体应用的说明

在主入口main.go中增加:

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/gin-swagger/swaggerFiles" // swagger embed files

以及针对该应用程序的api说明。

package main
import (
	"github.com/gin-gonic/gin"
	"github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"

	_ "github.com/swaggo/gin-swagger/example/docs"
)

// @title Swagger Example API
// @version 0.0.1
// @description  This is a sample server Petstore server.
// @BasePath /api/v1/
func main() {
	r := gin.New()
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.Run()
}

请注意@BasePath。 ?swagger注释中说明的@BasePath,,@Router而不是gin代码中声明的路径(没那么智能)。

具体api的说明

//
// @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]
func GetStringByInt(c *gin.Context) {
	err := web.APIError{}
	fmt.Println(err)
}

说明下几个参数。

如果不需要参数(例如,获取所有类型的,由url就齐活了),则不需要加@Param。参数可以是int或字符串类型。这里的定义会影响swagger ui发送的请求,如果定义错了会导致发送请求的数据不对,例如对数字进行了转义。

// @Param group body model.SwagGroupAdd true "Add group"
// @Param name path string true "Group Name"
// @Param role query int true "Role ID"

@Success和@Failure定义了返回值,类型可以是字符串,对象,数组。按照一般的restful定义,这三个类型足够表达返回值了。

GET /collection:返回资源对象的列表(数组)
GET /collection/resource:返回单个资源对象
POST /collection:返回新生成的资源对象
PUT /collection/resource:返回完整的资源对象
PATCH /collection/resource:返回完整的资源对象
DELETE /collection/resource:返回一个空文档

不过有些不太标准的restful实践会在上述返回之上再包装一个代码/消息/正文,所以对swaggo来说会造成一些新的负担,因为必须为这些返回类型单独加对应的类型。这项。

swag初始化

在项目根目录里执行swag init,生成docs/docs.go;再执行go run main.go,访问http://localhost:8080/swagger/index.html,就可以愉快的使用swagger ui了。

swag使用_第1张图片

你可能感兴趣的:(swag使用)