最近百家饭OpenAPI平台的JS API调用代码自动生成功能顺利进展中,进展情况可以关注我们的博客,我们计划先在内部完成“自举”(自己平台开发的功能支持自己的开发……),将百家饭平台自身的前后台交互部分迁移到自己开发的JS代码生成模式上来。

整个过程比较长,分成了golang部分和JavaScript部分,所以我们分篇来介绍,把其中有用的技术点也拎出来说

 百家饭平台后台是Golang开发的,用不上最成熟的Java Swagger模块,我们先要解决第一步的问题,就是让Golang支持OpenAPI接口文档自动生成和导出。

Golang下的类Java Swagger工具的开源工具,百家饭团队基于开源实现提供一个扩展版本:

按说明我们进行了安装:

go install github.com/extrame/swag/cmd/swag@latest

然后进到项目仓库下,运行下面的命令进行初始化:

swag init -o swag

上面自定义了输出目录为swag,命令默认会输出到doc目录,因为我们doc目录被代码用过了,所以选择了重新定义。

初步输出结果如下:

 几个文件都是空的内容:

 可见swag工具生成了符合OpenAPI v2.0的文档,只是内容现在还是空的。

输出基本信息

进一步阅读文档,得知,swag工具会从注释中生成OpenAPI文档中的相关信息,我们按照指引在main.go中增加基础的一些文档内容。主要是通过给main函数增加注释的方式进行。例如

// @contact.name   API Support
// @contact.url    https://rongapi.cn
// @contact.email  support@rongapi.cn
func main() {

这样, 就给OpenAPI文档增加了用户名,联系网址、邮箱等信息。

然后我们要开始进行接口文档最重要的部分,接口部分的输出了。

输出接口信息

接口信息的输出也很简单,基本逻辑是在具体的函数前面加上注释,注释内容的格式按swag命令要求的来就行,研究了一下,似乎什么函数都无所谓,主要还是注释在起作用。

基本的注释格式如下:

// List godoc
// @Summary      查询所有的公开API列表
// @Description  查询公开的和自己的API
// @Tags         api
// @Accept       x-www-form-urlencoded
// @Produce      json
// @Param        Limit  query     int      false  "单次获取个数"
// @Param        Self   query     boolean  false  "获取自己的"
// @Success      200    {array}   model.Source
// @Failure 200 {object} errors.Error
// @Router       /api/list [get]
func (o *Openapi) List(ctx *goblet.Context, args struct {
}

第一行是基本注释

第二行开始以@开头的就是各种swag标注了。

@Summary  标题

@Description 描述信息

@Tags 标签信息(按java格式,tags基本存储controller名称)

@Accept 输入要求的格式(x-www-form-urlencoded或者application/json等

@Produce 输出的格式

@Param 输入参数描述,从文档看是空格分隔的一个固定格式串(名称,位置,类型,是否必传,描述)(参考项目git页面提供的文档,应该还可以更复杂)

@Success,@Failure 不同情况下的返回,成功或者失败,也是一个固定格式串(状态码,类型,golang类型)(这里的golang类型是具体的返回数据类型格式,swag会去获取相关类型的具体内容)

@Router 具体路径和方法。

遇到的问题

然后还是执行开始的命令,按理我们就可以在输出目录得到文件了,但是我们的输出遇到了一些问题,导致我们无法继续:

找不到类型定义

2022/07/06 10:16:17 ParseComment error in file D:\workspace\baijiafan\product_site\ctrl\openapi.go :cannot find type definition: errors.Error

可以看到,我们在注释中为Faiure定义的返回类型errors.Error找不到,但是Success的model.Source是能找到的,我们的import如下:

 这就非常奇怪了。

按官方文档,我们尝试打开了工具的parseDependency选项,但是打开后又会报别的错。

输出格式错误

这个yaml项的说明看起来是另外的字段,实际代码如下:

原来是把注释掉的一些字段直接当成说明输出了。 

总的用下来,我们的感觉是swag工具确实是golang中生成openapi v2(swagger)文档的一个好用的工具,生成逻辑清楚,定义也较为简单,一些细节的地方需要更新,另外执行过程的透明度要增强,让这个工具更加能贴合普通用户的使用。

下一篇我们就来讲我们对于swag开源库的一些更改(更改已提交到原仓库,还没merge,还不能叫贡献)