go-zero插件goctl-swagger的坑

截至本文发布，直接安装goctl-swagger还无法解决指针问题

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

问题

go-zero可以通过goctl这个工具，通过插件goctl-swagger来将.api文件转化为swagger格式的json文件，该接口可以直接作为前后端的接口文档进行使用。

可以直接使用如下命令进行安装

go install github.com/zeromicro/goctl-swagger@latest

记住这个修改时间，要考????

然后创建一个目录，在目录下初始化项目go mod init user，在目录下创建一个api文件夹。在api目录下可以用goctl生成user.api文件，也可以自己写

goctl api go -api user.api -dir .

作为演示，此处的user.api文件比较简单

type (
    CreateRequest {
        Name string `json:"name"`
        Email string `json:"email"`
    }
    CreateResponse {
        Id int64 `json:"id"`
    }
)

service user-api {
	@handler CreateUser
    post /user(CreateRequest) returns (CreateResponse)
}

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

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

以上都很完美，直到将字段改为指针。

将user.api进行简单的更改之后

type (
    CreateRequest {
        Name *string `json:"name"`
        Email *string `json:"email"`
    }
    CreateResponse {
        Id *int64 `json:"id"`
    }
)

service user-api {
	@handler CreateUser
    post /user(CreateRequest) returns (CreateResponse)
}

然后重新生成user.json并打开就会如下所示

这是因为目前goctl-swagaer直接安装版本还未支持指针的格式

解决

该问题在最新版的源码中已经修复了，但是作者没有打包????。所以想解决这个问题的话，需要clone源码，在本地编译后将其替换掉我们安装时的可执行文件即可

然后重新执行生成文档的命令，生成的文档就好了

过程

刚开始出现这个问题时，肯定是面向google编程，结果出来的都是一堆教怎么生成文档的，然后我看都是没有指针，就先把我自己的文件的指针去掉了一部分，发现去掉了的就好了，所以就怀疑作者没支持指针的类型，就跑到项目源码上去看了眼。

然后赫然发现就有这么一个问题，差不多一年前的问题，而且还是0回复，不知道该说提问者惨啊还是作者懒啊????

接着我就下载了源码，一步步进行查看，然后找到了这个map，此处没有复制完

var swaggerMapTypes = map[string]reflect.Kind{
	"string":   reflect.String,
	"*string":  reflect.String,
	"int":      reflect.Int,
	"*int":     reflect.Int,
}

但是这个里面支持指针啊！！！

然后我看到在这个项目下有example，我就修改了example下的文件，然后执行，结果可想而知。然后一时之间就没想起来把这个项目编译了来运行????

等后面想起来之后，我将该项目编译之后再次运行发现以及可以了

goctl api plugin -plugin D:\Projects\go\go-zero\goctl-swagger\main.exe="swagger --filename user.json" -api user.api -dir .

所以，最后只需要将main.exe改为goctl-swagger替换掉之前安装的那个就可以了

新问题

在后续的使用过程中，我发现可以对user.api的service指定group

就比如之前可能是这样的

指定group之后就变这样的了

然后我把它变成中文

@server (
    group : 角色
)

service user-api {
    @doc (
        summary : "新建角色"
    )
    @handler CreateRole
    post /role(CreateRequest) returns (CreateResponse)
}

它倒是可以