[zeromicro/go-zero]建议:增加自动生成swagger文档功能

2020-09-25 142 views
2

建议:利用反射获取结构体注解的文档注释,自动生成swagger文档 可参考:https://github.com/henrylee2cn/apiware 项目实现。 Apiware将Go语言net/http及fasthttp请求的指定参数绑定到结构体,并验证参数值的合法性。 建议您可以使用结构体作为web框架的Handler,并用该中间件快速绑定请求参数,节省了大量参数类型转换与有效性验证的工作。同时还可以通过该结构体标签,创建swagger的json配置文件,轻松创建api文档服务。

回答

9

感谢您的建议,不打算支持swagger哈,api定义太冗长了,不符合我们的设计思路

2
  • 目前生成的文档是偏弱的。而且我觉得rest api 文档应该是语言无关的,目前goctl会把.api文件中的定义拷贝到Markdown中,而.api文件中的定义方式又和golang语法很相似。
  • swagger是目前open api的唯一实现,有余力的情况下建议还是要支持(项目要得到广泛推广,必然应该支持公认的普世标准,不能自己玩自己的)。
  • 不太同意swagger api定义太冗长了的观点,准确、严谨的定义必然比近似的定义冗长。
9

目前不打算支持,你可以对比下我们的语法表示和swagger的表示

6

可以不生成swagger格式,是不是可以把目前的 *.api 生成其他更好解析的格式 比如 json yaml,大家根据这个自己生成自己需要的api文档格式