526互联

go-zero插件goctl-swagger的坑——第二弹

发布时间 2023-07-22 23:00:13作者: 丶吃鱼的猫

截至本文发布，直接安装goctl-swagger还无法解决go-zero .api文件引入问题

该文主要是记录在使用过程中遇到的问题和解决思路，不做详细教学使用。

问题

在go-zero插件goctl-swagger的坑的基础上，本文带来新的问题。也就是在开头说到的go- zero的.api文件相互引用问题。

在最新的go-zero中，对于.api文件支持了公共文件的引用，这对于我们编写api相当的友好，通用的返回结构可以实现在各个模块的重用。

作为演示，以goctl-swagger的example下的user.api文件进行简单修改

import (
	"./common/common.api"
)

type (
	UserInfoReply {
		Name        string     `json:"name"`
		Age         int        `json:"age"`
		Birthday    string     `json:"birthday"`
		Description string     `json:"description"`
		Tag         []string   `json:"tag"`
		Tags        [][]string `json:"tags"`
	}
)

@server(
	prefix: /api
)

service user-api {
	@handler getUserInfo
	get /user/:id (GetReq) returns (UserInfoReply)
	
}

在同目录下建立common/common.api文件，添加如下内容

type (
    GetReq {
        Id int64 `path:"id"`
    }
)

然后用如下命令生成user.json的接口文档

goctl api plugin -plugin goctl-swagger="swagger -filename user.json" -api user.api -dir .

此时，goctl-swagger会直接报错，导致无法生成api文档

\goctl-swagger\example\user.api line 2:1  mismatched 'import value', found input '"./common/common.api"'
goctl-swagger: \goctl-swagger\example\user.api line 2:1  mismatched 'import value', found input '"./common/common.api"'

image-20230722224748539

这是因为之前的goctl-swagger中的go-zero版本还是较低的版本，不支持引入其他.api文件

解决

找到问题之后解决问题也就比较简单了，我们只需要clone源码，在本地修改go.mod中关于go-zero的版本到最新版之后，然后编译将其替换掉我们安装时的可执行文件即可

image-20230722225223454

然后重新执行生成文档的命令，生成的文档就好了，可以看到此时执行该命令也没有报错

image-20230722223618945

同时在目录下也多出了对应的api文件

image-20230722224809168