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

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

1. 第一篇：Golang生成OpenAPI接口文档（Swag工具试用）

2. 第二篇：Golang OpenAPI工具Swag修正

3. 第三篇：Golang OpenAPI工具Swag修正-go ast篇

4. 第四篇：也谈Javascript里的commonjs模块和es6模块

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

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

swaggo/swag: Automatically generate RESTful API documentation with Swagger 2.0 for Go. (github.com)

按说明我们进行了安装：

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，还不能叫贡献）