GoFrame框架支持全自动化的接口文档生成,保障代码与接口文档同步维护,自动生成的接口文档采用的是标准的OpenAPIv3协议。在介绍OpenAPIv3协议之前,建议您先阅读了解框架的规范路由特性:路由注册-规范路由 。
GoFrame
OpenAPIv3
自动生成API文档真的很方便,能在给一些自定义OpenAPIv3的示例吗?比如想实现全局请求头等,试了好久都不生效
参数中
type AccountAuth struct { AuthAccountNo uint64 `json:"authAccountNo" dc:"Account number 通过token获取"` AuthAccountType uint `json:"authAccountType" dc:"Account type 通过token获取 前端不需要处理"` AuthAccountLevel uint `json:"authAccountLevel" dc:"Account level 通过token获取 前端不需要处理"` AuthTime int64 `json:"authTime" dc:"Auth time 通过token获取"` AuthSource string `json:"authSource" dc:"Auth source 通过token获取"` Token string `json:"token" v:"required" in:"header"` }
token就会显示到header中
method:ALL应该咋写啊。
具体请查看常见问题:路由注册-规范路由
请问,为什么我的swagger里data没有解析数据的具体字段,需要哪些特别配置吗?
配置了 `openapiPath` 吗?
type EchoSayRes struct { Content string `dc:"Reply content" example:"Hello, I'm echo"` }
字段的example 删除 或许留空
这个swagger不能运行吗,而且截图里面的response是啥
不可以
gf 2.0.1之后,文档UI使用的redoc, redoc 没有try it console。如果想使用旧版的swaggerUI,可以使用gf v2.0.0-rc3版本
我同样和你的疑问.resposnse也不清楚从哪里来的,这个框架看着挺好,弊病是示例代码部分都太断章取义了,随意截取一段就完事了,让新手来说摸不到边际.
新版本的swagger 最好支持在线发送请求,这样方便前端开发人员测试接口
已支持自定义UI 接口文档-自定义UI - GoFrame (ZH)-Latest - GoFrame官网 - 类似PHP-Laravel, Java-SpringBoot的Go企业级开发框架
想问一下,如果请求的body内容是数组,请求结构体要怎么定义。
POST ip:port/bcf/2.1/projects/{projectGuid}/topics/{topicGuid}/files
body:
[ { "ifc_project": "string", "ifc_spatial_structure_element": "string", "file_name": "string", "date": "string", "reference": "string" }]
type FileReqItem struct { Ifc_project string Ifc_spatial_structure_element File_name Date Reference } type FileReq struct { Item: []FileReqItem }
请问,多文件上传接口、与文件下载接口,接口meta与方法参数如何编写?
接口文档支持category或才group吗,现在只是根据tags分,但是正常都是需要区分前后台接口,需要区分小程序、app、等不同业务线的接口,所以希望能支持下
func (c *Cmd) Send(r *ghttp.Request) {} 格式的接口呢? 始终生成不了swagger 文档 ?????????
这种写法肯定是生不活的
OK,框架自断一腿
另外,如实例,多增加一个函数 (SayHi),好像也无效
type HelloReq struct { g.Meta `path:"/" method:"get"` Name string `v:"required" dc:"Your name"` } type HelloRes struct { Reply string `json:"reply" dc:"返回值"` } type Hello struct{} func (h *Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) { g.Log().Infof(ctx, `receive say: %+v`, req) res = &HelloRes{ Reply: fmt.Sprintf(`Hi %s`, req.Name), } return } func (h *Hello) SayHi(ctx context.Context, req *HelloReq) (res *HelloRes, err error) { g.Log().Infof(ctx, `receive say: %+v`, req) res = &HelloRes{ Reply: fmt.Sprintf(`Say Hi %s`, req.Name), } return }
g.Meta `path:"/" method:"get" summary:"接口是啥" tags:"我是哪个组的"` 这个要加个 tags, summary,看下文档
还有,swagger要打开,openApi也可以打开
打开了~ 如示例的(只有一个 Say 函数的)可行。
但是新增一个几乎同样的 SayHi,就不行了
同一个对象下面尝试注册多个方法为 handler,就是没成功~ 求个例子
GoFrame学习之路 可以参考这个
看了一下,版本信息对上了,其他内容不是很对症
但,找到处理方法了(原因未知,也许和之前 1.6/2.x 混用有关)
我也想知道如何才能手动注册 openapi,还有生成的 openapi中的 omitempty 怎么去掉
这种命名的约定也是叫人很无奈。。。过度约束了
invalid struct naming for response: defined as "%s", but it should be named with "Res" suffix like "XxxRes"
我觉得也是,不明白为什么要强制以Req和Res结尾
命名规范
个人觉得框架不应该限制命名,这个应该团队来约定,框架做这些有些过度约束了,强迫症看了表示难受 (๑*◡*๑)
个人水平有限,感觉框架越来越复杂,看得越来越懵逼。
适配的场景越多,复杂性必然上升。
好的框架,能隔离复杂场景和简单场景。
gf 的成熟度还欠缺
如果有好的点,可以issue描述具体的case,可以一起参与完善,非常欢迎社区贡献。
issue
case
规范路由是稍微复杂一点,本质其实就是结构化输入输出、通过标签来维护接口文档。
我是从codeigniter,到beego,现在来看goframe,用惯了beego的目录结构,现在来看goframe的是有些别扭。beego是注解路由文档。
goframe的老版本也是用的注解,弊端挺多的,所以新版本就改为了结构化及标签形式的,具体介绍可以参考:路由注册-规范路由
goframe
v标签生成 open api返回的数据和swagger-ui不兼容,如:get请求定义v:required,在swagger-ui内规则判断为输入框必须输入required这个单词,是否有解,还是只能用默认的redoc
gf生成的openAPI文档api.json,required参数设置有问题 · Issue #1798 · gogf/gf (github.com) bug
请教下,按照以下focus-single项目示例代码,更改openapi全局默认response,这种情况下如何自定义openapi response,有没有示例?一些接口不是完全按照规范的,比如登陆接口返回的是: {"code": 0, "token": "", "expire": "", "data": ""}
focus-single
// focus-single项目示例代码 openapi := s.GetOpenApi() openapi.Config.CommonResponse = ghttp.DefaultHandlerResponse{} openapi.Config.CommonResponseDataField = `Data`
大概看了下源码,如果response添加了mime就会忽略CommonResponse。这应该不是规范方法,我是偷懒了,先用。希望能有个规范的方法。
gf默认生成的是OpenAPI3协议的,可以降成2的吗?用openapi3协议的json文件再Yapi页面上导入的时候会报错
请问一下如何在规范路由模式下去掉默认添加的 bail 规则呀?,我想要拿到请求验证的所有错误而不是只有第一条,本来想不用规范路由直接来但是好像这样又不会自动生成 swagger
43 Comments
富贵 Rich
自动生成API文档真的很方便,能在给一些自定义
OpenAPIv3
的示例吗?比如想实现全局请求头等,试了好久都不生效智刚
参数中
token就会显示到header中
edzhao
method:ALL应该咋写啊。
郭强
具体请查看常见问题:路由注册-规范路由
comien
请问,为什么我的swagger里data没有解析数据的具体字段,需要哪些特别配置吗?
智刚
配置了 `openapiPath` 吗?
智刚
字段的example 删除 或许留空
jayce young
这个swagger不能运行吗,而且截图里面的response是啥
智刚
不可以
白夜
gf 2.0.1之后,文档UI使用的redoc, redoc 没有try it console。如果想使用旧版的swaggerUI,可以使用gf v2.0.0-rc3版本
youxue2016
我同样和你的疑问.resposnse也不清楚从哪里来的,这个框架看着挺好,弊病是示例代码部分都太断章取义了,随意截取一段就完事了,让新手来说摸不到边际.
zhaosy
新版本的swagger 最好支持在线发送请求,这样方便前端开发人员测试接口
白夜
gf 2.0.1之后,文档UI使用的redoc, redoc 没有try it console。如果想使用旧版的swaggerUI,可以使用gf v2.0.0-rc3版本
海亮
已支持自定义UI 接口文档-自定义UI - GoFrame (ZH)-Latest - GoFrame官网 - 类似PHP-Laravel, Java-SpringBoot的Go企业级开发框架
cl944083851
想问一下,如果请求的body内容是数组,请求结构体要怎么定义。
POST ip:port/bcf/2.1/projects/{projectGuid}/topics/{topicGuid}/files
body:
[
{
"ifc_project": "string",
"ifc_spatial_structure_element": "string",
"file_name": "string",
"date": "string",
"reference": "string"
}
]
白夜
stephen
请问,多文件上传接口、与文件下载接口,接口meta与方法参数如何编写?
willem
接口文档支持category或才group吗,现在只是根据tags分,但是正常都是需要区分前后台接口,需要区分小程序、app、等不同业务线的接口,所以希望能支持下
卡卡
willem
这种写法肯定是生不活的
卡卡
OK,框架自断一腿
另外,如实例,多增加一个函数 (SayHi),好像也无效
willem
还有,swagger要打开,openApi也可以打开
卡卡
打开了~ 如示例的(只有一个 Say 函数的)可行。
但是新增一个几乎同样的 SayHi,就不行了
卡卡
同一个对象下面尝试注册多个方法为 handler,就是没成功~ 求个例子
白夜
GoFrame学习之路 可以参考这个
卡卡
看了一下,版本信息对上了,其他内容不是很对症
但,找到处理方法了(原因未知,也许和之前 1.6/2.x 混用有关)
chamhaw
我也想知道如何才能手动注册 openapi,还有生成的 openapi中的 omitempty 怎么去掉
卡卡
这种命名的约定也是叫人很无奈。。。过度约束了
流星
我觉得也是,不明白为什么要强制以Req和Res结尾
郭强
命名规范
流星
个人觉得框架不应该限制命名,这个应该团队来约定,框架做这些有些过度约束了,强迫症看了表示难受 (๑*◡*๑)
零基础菜鸟
个人水平有限,感觉框架越来越复杂,看得越来越懵逼。
卡卡
适配的场景越多,复杂性必然上升。
好的框架,能隔离复杂场景和简单场景。
gf 的成熟度还欠缺
郭强
如果有好的点,可以
issue
描述具体的case
,可以一起参与完善,非常欢迎社区贡献。郭强
规范路由是稍微复杂一点,本质其实就是结构化输入输出、通过标签来维护接口文档。
chaegumi
我是从codeigniter,到beego,现在来看goframe,用惯了beego的目录结构,现在来看goframe的是有些别扭。beego是注解路由文档。
郭强
goframe
的老版本也是用的注解,弊端挺多的,所以新版本就改为了结构化及标签形式的,具体介绍可以参考:路由注册-规范路由lickman
v标签生成 open api返回的数据和swagger-ui不兼容,如:get请求定义v:required,在swagger-ui内规则判断为输入框必须输入required这个单词,是否有解,还是只能用默认的redoc
白夜
gf生成的openAPI文档api.json,required参数设置有问题 · Issue #1798 · gogf/gf (github.com) bug
shensw
请教下,按照以下
focus-single
项目示例代码,更改openapi全局默认response,这种情况下如何自定义openapi response,有没有示例?一些接口不是完全按照规范的,比如登陆接口返回的是: {"code": 0, "token": "", "expire": "", "data": ""}shensw
大概看了下源码,如果response添加了mime就会忽略CommonResponse。这应该不是规范方法,我是偷懒了,先用。希望能有个规范的方法。
石小志
gf默认生成的是OpenAPI3协议的,可以降成2的吗?用openapi3协议的json文件再Yapi页面上导入的时候会报错
huruhi
请问一下如何在规范路由模式下去掉默认添加的 bail 规则呀?,我想要拿到请求验证的所有错误而不是只有第一条,本来想不用规范路由直接来但是好像这样又不会自动生成 swagger