swagger 注解的优化

[waltcow]

    // swagger:route DELETE /user user deleteUser
    // Delete user information | 删除用户信息
    // Parameters:
    //  + name: body
    //    require: true
    //    in: body
    //    type: IDReq
    // Responses:
    //   200: SimpleMsg
    //   401: SimpleMsg
    //   500: SimpleMsg
    @handler deleteUser
    delete /user (IDReq) returns (SimpleMsg)

现在感觉api文件过于重复显得臃肿。 如果结合 gozero api 已有语法 @doc， 可以删减一些重复的定义， 譬如 // swagger:route DELETE /user user deleteUser 在api文件parse的过程中，应该可以推出类似的swagger 路由信息

[suyuan32]

你这个只是需要改下生成逻辑，但是我觉得拆分出来就会被定死了，有些用户要有多个tag或者别名怎么弄？直接集成go-swagger默认的注解感觉好一点

[waltcow]

好吧，让我再想想👀

[waltcow]

@suyuan32

稍微diy了一下 https://github.com/go-slash/go-zero-enhanced/commit/f6ab4f83f0dd63b9133380b6c8296f156973a19f

    @doc(
        summary: "Update user's profile | 更新用户个人信息"
        description: "更新用户个人信息"
    )
    @handler updateUserProfile
    post /user/profile (ProfileReq) returns (SimpleMsg)

==>

// swagger:route post /user/profile user UpdateUserProfile
//
// "Update user's profile | 更新用户个人信息"
//
// "更新用户个人信息"
//
// Parameters:
//  + name: body
//    require: true
//    in: body
//    type: ProfileReq
//
//
// Responses:
//  200: SimpleMsg
//
//

[suyuan32]

看起来可以，你修改完善点提交PR给我测试下，注意要把API文件也改了

[suyuan32]

@waltcow

[suyuan32]

注意有些是没有 parameters 的

[suyuan32]

还有就是需要多运行 goctls doc命令嘛？

[suyuan32]

https://goswagger.io/use/spec/route.html

[suyuan32]

还有最大的问题是用户没办法使用全部go-swagger的注解，还需要深入考虑下，生成虽然方便了，但是可修改的功能变少了

[waltcow]

看起来可以，你修改完善点提交PR给我测试下，注意要把API文件也改了

明天我再完善一下，把genStruct的注解生成也处理了

[suyuan32]

还有就是结构体的注解也需要解析

[suyuan32]

[suyuan32]

生成代码会简洁些，后续用户要自己定制的话得自己去handler修改，不过可以少写很多注释，效率应该高些

[suyuan32]

@waltcow 注解生成弄得咋样了，我准备升级下goctl, 文件名以后还是采用下划线吧，之前用的是默认的文件名，太难分辨了，原来还有 style参数可选的，没注意

[waltcow]

@suyuan32

https://github.com/go-slash/go-zero-enhanced 我的Fork也参考你的做了类似的修改，但没把GORM，Casbin， Consul的东西集成

在 goctls api go cli 中加入--swagger 开启swagger注解生成, 把swagger的注解加入进去，

人为的把Resp, Req 结尾的struct 归类成swagger:response 和 swagger:model

现在用着还可以

[waltcow]

https://github.com/zeromicro/go-zero/pull/2528

@suyuan32 最近看了下这个PR，感觉在验证和openapi doc生成上可以做的更优雅

[suyuan32]

改了好多呀，主要区别是啥？有没有生成的文件看下效果？

[suyuan32]

@waltcow

[waltcow]

改了好多呀，主要区别是啥？有没有生成的文件看下效果？

主要是不用生成swagger 的annotations.直接扩充了api的spec和parse 结果，再生成openapi doc

[suyuan32]

简单看了下，不是很清楚好在哪。。。

openapi 和 swagger 的配置文件有啥区别？也没有示例文档介绍

[suyuan32]

他通过定义注释的标签来实现？

[suyuan32]

这些 go-swagger 不是已经实现了嘛 @waltcow

[suyuan32]

看起来重复造轮子了

[suyuan32]

目前来说也就是 response 和 model需要 annotations, route现在已经生成好了，他只是将 go-swagger 的功能集成到 goctl中，好处是不需要文件里有注释？

[waltcow]

目前来说也就是 response 和 model需要 annotations, route现在已经生成好了，他只是将 go-swagger 的功能集成到 goctl中，好处是不需要文件里有注释？

是的，无需再次用go swagger 再去提取doc 再生成apidoc

[suyuan32]

但是感觉也没少写多少，多于注释来说，只是文件里面没有了注解，还有就是少运行一条命令，考虑考虑，因为他的validator啥的都是自己实现的，实际上handler和type里面多了好多validate

[suyuan32]

[suyuan32]

没搞懂为啥要自己实现validator

[suyuan32]

playground 里面不是已经实现了嘛，国际化他这个不支持

[suyuan32]

我的框架有外国人用的，尽量支持多语言

[suyuan32]

他只支持英文返回

[suyuan32]

[suyuan32]

支持的种类也不如 https://github.com/go-playground/validator

[suyuan32]

是通过 一个注解同时生成了 swagger 和 validator的代码，也意味着需要自己维护swagger 和 validator ...

[suyuan32]

@waltcow

[waltcow]

是通过 一个注解同时生成了 swagger 和 validator的代码，也意味着需要自己维护swagger 和 validator ...

我再仔细看完PR修改 发现只是用openapi doc 生成 api文件，和我刚开始的想象不太一样😭

[ddzrc]

是通过 一个注解同时生成了 swagger 和 validator的代码，也意味着需要自己维护swagger 和 validator ...

我再仔细看完PR修改 发现只是用openapi doc 生成 api文件，和我刚开始的想象不太一样sob

能通过解析 openapi2.0/3.0 文档生成脚手架代码，没有生成.api 文件

[ddzrc]

是通过 一个注解同时生成了 swagger 和 validator的代码，也意味着需要自己维护swagger 和 validator ...

swagger/ openapi 中可以 定义参数校验， 不需要定义注解

[ddzrc]

没搞懂为啥要自己实现validator

当时考虑过， go-zero自带的校验， 和https://github.com/go-playground/validator， openapi 的校验功能比 go-zero 要多很多，go-playground 主要考虑到性能损耗也放弃了

[suyuan32]

是通过 一个注解同时生成了 swagger 和 validator的代码，也意味着需要自己维护swagger 和 validator ...

我再仔细看完PR修改 发现只是用openapi doc 生成 api文件，和我刚开始的想象不太一样sob

能通过解析 openapi2.0/3.0 文档生成脚手架代码，没有生成.api 文件

openapi 文档前端提供？和写api有啥区别，感觉和官方不兼容，openapi生成的代码api文件里没有，感觉只能二选一，优点可能是openapi 可以使用软件可视化生成？go-playground 需要解析tag性能是会有损耗，看接口需求吧。考虑性能的话框架不能太重，考虑功能丰富的话性能又难满足.

[suyuan32]

而且有点难维护，validator代码改一下就得重新生成一次工具 @ddzrc

[suyuan32]

而且有点难维护，validator代码改一下就得重新生成一次工具 @ddzrc

[ddzrc]

是通过 一个注解同时生成了 swagger 和 validator的代码，也意味着需要自己维护swagger 和 validator ...

我再仔细看完PR修改 发现只是用openapi doc 生成 api文件，和我刚开始的想象不太一样sob

能通过解析 openapi2.0/3.0 文档生成脚手架代码，没有生成.api 文件

openapi 文档前端提供？和写api有啥区别，感觉和官方不兼容，openapi生成的代码api文件里没有，感觉只能二选一，优点可能是openapi 可以使用软件可视化生成？go-playground 需要解析tag性能是会有损耗，看接口需求吧。考虑性能的话框架不能太重，考虑功能丰富的话性能又难满足.

一般来说谁提供接口，谁提供 openapi/swagger 文档， 相比官方解析 .api文件，只多了出参和入参 的 validate 方法，其他都一致

[ddzrc]

而且有点难维护，validator代码改一下就得重新生成一次工具

这个 swagger/openapi 注重对接，是从文档到代码， 而不是先修改代码，再修改文档

[suyuan32]

看不同需求吧，我们这边是通过api生成swagger, 官方的态度是api基本就是文档的功能，如果需要添加额外定制的话只能自己fork修改使用，你写的功能属于增加了新的解析功能，感觉官方比较难采纳，你这个的好处我感觉是前端方便了，前端直接编写api给后端使用，go zero反过来是后端写好接口给前端调用，对接来说是快了些，但前提是前端文档设计要合理，不然字段啥的设计不符合后端要求的话也麻烦

[suyuan32]

对前端的要求高了

[suyuan32]

文档不合理的话后端只能干着急了

[ddzrc]

但前提是前端文档设计要合理，不然字段啥的设计不符合后端要求的话也麻烦

谁写文档的话，看业务，和团队吧， 我见过很多公司，是后端来写文档， 不过 open/swagger 编写的成本确实很高

[waltcow]

通过扩展API的语法，生成项目脚手架 和 OpenAPI 接口定义，我觉得这样比较简单点 @suyuan32 @ddzrc

[noahlann]

对于routes的parameters，目前是定义为

Parameters:
  + name: body
     required: true
     in: query
     type: OauthLoginReq

想问一个问题，就是我有一个 get /oauth/login oauthprovider OauthLogin

参数放置于 query 中，如何才能在 swagger 中将query（也即是 form）展现出来并测试请求呢？

是不是需要手动将 OauthLoginReq 拆解，并写为多个 parameters，然后修改 handler 中的注释吗？

---

简单点说，就是如何支持 query(form) 参数 / path参数 / header参数 的 swagger 文档生成？

不是很懂。。 我看 genhandlers 中并没有收集到所有的信息，不知道怎么去实现。