一些不错的接口文档管理方案

留言

应该是从mylab开始意识到文档管理的重要性，因为要和前端对接，当时用的是gitbook，有一个git仓库，在里面写markdown，然后提交，gitbook会自动生成前端页面

之后hp开始接触到swagger，感觉很难用。。其实很大原因是使用方式不对

两家大厂，用的都是类似纯doc的文档去管理接口…或者用飞书文档

在argment，go-zero生成swagger，导入到apifox里面

在arcv，用echo框架，新增接口时，在controller层的对应func上方新增如下注释:

1
2
3
4
5
6
7
8
// SysLogList
// @version 3.6.0
// @Title SysLogList
// @Tags 日志
// @Summary 系统日志列表
// @Description 展示系统日志的名称，最后修改时间和大小
// @Success 200 {object} model.Response{data=[]model.SysLogListResponse}
// @Router /api/v2/log/sysloglist [GET]

将相应改动上传

然后去文档构建服务器

拉取最新的代码，执行 swag init --parseDependency --parseInternal -g ./cmd/main.go

此时会看到类似如下输出:

1
2
2023/05/19 17:05:58 Generate swagger docs....
2023/05/19 17:05:58 Generate general API Info, search dir:./

（下面这样操作，完全是为了特殊case，不想把文档打包进去。所以使用了tag标签。。。

此时将会在docs下，生成最新的swagger.json和swagger.yaml文档。用这两个新文件，替换/usr/local/arcvideo/arcbox/docs目录下的同名文件

而后在项目根目录下执行 go build -tags doc -ldflags="-s -w" -o box_server ./cmd && mv box_server /usr/local/arcvideo/arcbox/ && service arcbox-server stop && service arcbox-server start
）

此时刷新http://10.9.100.154/api/swagger/doc.json,能搜索到最新的改动。

同时apifox如果配置了自动同步，也会自动更新

文章目录