Golang 生成 OpenAPI 接口文档
最近百家饭 OpenAPI 平台的 JS API 调用代码自动生成功能顺利进展中，进展情况可以关注我的博客，我们计划先在内部完成“自举”（自己平台开发的功能支持自己的开发……），将百家饭平台自身的前后台交互部分迁移到自己开发的 JS 代码生成模式上来。
整个过程比较长，分成了 golang 部分和 JavaScript 部分，所以我们分篇来介绍，把其中有用的技术点也拎出来说
第一篇：Golang 生成 OpenAPI 接口文档（Swag 工具试用）
第二篇：Golang OpenAPI 工具 Swag 修正
第三篇：Golang OpenAPI 工具 Swag 修正-go ast 篇
第四篇：也谈 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)
按说明我们进行了安装：
然后进到项目仓库下，运行下面的命令进行初始化：
上面自定义了输出目录为 swag，命令默认会输出到 doc 目录，因为我们 doc 目录被代码用过了，所以选择了重新定义。
初步输出结果如下：
几个文件都是空的内容：
可见 swag 工具生成了符合 OpenAPI v2.0 的文档，只是内容现在还是空的。
输出基本信息
进一步阅读文档，得知，swag 工具会从注释中生成 OpenAPI 文档中的相关信息，我们按照指引在 main.go 中增加基础的一些文档内容。主要是通过给 main 函数增加注释的方式进行。例如
这样， 就给 OpenAPI 文档增加了用户名，联系网址、邮箱等信息。
然后我们要开始进行接口文档最重要的部分，接口部分的输出了。
输出接口信息
接口信息的输出也很简单，基本逻辑是在具体的函数前面加上注释，注释内容的格式按 swag 命令要求的来就行，研究了一下，似乎什么函数都无所谓，主要还是注释在起作用。
基本的注释格式如下：
第一行是基本注释
第二行开始以 @开头的就是各种 swag 标注了。
@Summary 标题
@Description 描述信息
@Tags 标签信息（按 java 格式，tags 基本存储 controller 名称）
@Accept 输入要求的格式(x-www-form-urlencoded 或者 application/json 等
@Produce 输出的格式
@Param 输入参数描述，从文档看是空格分隔的一个固定格式串（名称，位置，类型，是否必传，描述）（参考项目 git 页面提供的文档，应该还可以更复杂）
@Success，@Failure 不同情况下的返回，成功或者失败，也是一个固定格式串（状态码，类型，golang 类型）（这里的 golang 类型是具体的返回数据类型格式，swag 会去获取相关类型的具体内容）
@Router 具体路径和方法。
遇到的问题
找不到类型定义
然后还是执行开始的命令，按理我们就可以在输出目录得到文件了，但是我们的输出遇到了一些问题，导致我们无法继续：
可以看到，我们在注释中为 Faiure 定义的返回类型 errors.Error 找不到，但是 Success 的 model.Source 是能找到的，我们的 import 如下：
这就非常奇怪了。
按官方文档，我们尝试打开了工具的 parseDependency 选项，但是打开后又会报别的错。
输出格式错误
某些字段有格式错误问题，比如这个 yaml 项的说明看起来是另外的字段，实际代码如下：
原来是把注释掉的一些字段直接当成说明输出了。
总的用下来，我们的感觉是 swag 工具确实是 golang 中生成 openapi v2（swagger）文档的一个好用的工具，生成逻辑清楚，定义也较为简单，一些细节的地方需要更新，另外执行过程的透明度要增强，让这个工具更加能贴合普通用户的使用。
下一篇我们就来讲我们对于 swag 开源库的一些更改（更改已提交到原仓库，还没 merge，还不能叫贡献）
版权声明: 本文为 InfoQ 作者【百家饭隐私计算平台创业者】的原创文章。
原文链接:【http://xie.infoq.cn/article/94f185cda156c6f9142d55446】。文章转载请联系作者。
低代码API对接+隐私计算 2022.06.06 加入
通过低代码工具完成API对接，结合多方计算技术实现API的隐私计算。本号主要发布创业过程中的其他相关故事，技术探索。主要创业故事见知乎或微信"百家饭隐私计算"号 https://rongapi.cn
评论