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 最好支持在线发送请求，这样方便前端开发人员测试接口
想问一下，如果请求的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
42 Comments
富贵 Rich
自动生成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中
edzhao
method:ALL应该咋写啊。
郭强
具体请查看常见问题：路由注册-规范路由
comien
请问，为什么我的swagger里data没有解析数据的具体字段，需要哪些特别配置吗？
智刚
配置了 `openapiPath` 吗？
智刚
type EchoSayRes struct { Content string `dc:"Reply content" example:"Hello, I'm echo"` }字段的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版本
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"
}
]
白夜
type FileReqItem struct { Ifc_project string Ifc_spatial_structure_element File_name Date Reference } type FileReq struct { Item: []FileReqItem }stephen
请问，多文件上传接口、与文件下载接口，接口meta与方法参数如何编写？
willem
接口文档支持category或才group吗，现在只是根据tags分，但是正常都是需要区分前后台接口，需要区分小程序、app、等不同业务线的接口，所以希望能支持下
卡卡
willem
这种写法肯定是生不活的
卡卡
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 }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": ""}// focus-single项目示例代码 openapi := s.GetOpenApi() openapi.Config.CommonResponse = ghttp.DefaultHandlerResponse{} openapi.Config.CommonResponseDataField = `Data`shensw
大概看了下源码，如果response添加了mime就会忽略CommonResponse。这应该不是规范方法，我是偷懒了，先用。希望能有个规范的方法。
石小志
gf默认生成的是OpenAPI3协议的，可以降成2的吗？用openapi3协议的json文件再Yapi页面上导入的时候会报错
huruhi
请问一下如何在规范路由模式下去掉默认添加的 bail 规则呀？，我想要拿到请求验证的所有错误而不是只有第一条，本来想不用规范路由直接来但是好像这样又不会自动生成 swagger