基本介绍

GoFrame框架支持全自动化的接口文档生成,保障代码与接口文档同步维护,自动生成的接口文档采用的是标准的OpenAPIv3协议。在介绍OpenAPIv3协议之前,建议您先阅读了解框架的规范路由特性:路由注册-规范路由

相关文档

Content Menu

  • No labels

43 Comments

  1. 自动生成API文档真的很方便,能在给一些自定义OpenAPIv3的示例吗?比如想实现全局请求头等,试了好久都不生效

    1. 参数中 

      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

  2. method:ALL应该咋写啊。

    1. 具体请查看常见问题:路由注册-规范路由

  3. 请问,为什么我的swagger里data没有解析数据的具体字段,需要哪些特别配置吗?

    1. 配置了 `openapiPath` 吗?

    2. type EchoSayRes struct {
      	Content string `dc:"Reply content" example:"Hello, I'm echo"`
      }

      字段的example 删除 或许留空

  4. 这个swagger不能运行吗,而且截图里面的response是啥

      1. gf 2.0.1之后,文档UI使用的redoc, redoc 没有try it console。如果想使用旧版的swaggerUI,可以使用gf v2.0.0-rc3版本

    1. 我同样和你的疑问.resposnse也不清楚从哪里来的,这个框架看着挺好,弊病是示例代码部分都太断章取义了,随意截取一段就完事了,让新手来说摸不到边际.

  5. 新版本的swagger  最好支持在线发送请求,这样方便前端开发人员测试接口

    1. gf 2.0.1之后,文档UI使用的redoc, redoc 没有try it console。如果想使用旧版的swaggerUI,可以使用gf v2.0.0-rc3版本

  6. 想问一下,如果请求的body内容是数组,请求结构体要怎么定义。

    POST ip:port/bcf/2.1/projects/{projectGuid}/topics/{topicGuid}/files



    pathstring


    pathstring

    body:

    [
      {
        "ifc_project": "string",
        "ifc_spatial_structure_element": "string",
        "file_name": "string",
        "date": "string",
        "reference": "string"
      }
    ]

    1. type FileReqItem struct {
          Ifc_project string                
          Ifc_spatial_structure_element     
          File_name                          
          Date                             
          Reference                          
      	}
      
      type FileReq struct {
          Item: []FileReqItem                          
      	}
  7. 请问,多文件上传接口、与文件下载接口,接口meta与方法参数如何编写?

  8. 接口文档支持category或才group吗,现在只是根据tags分,但是正常都是需要区分前后台接口,需要区分小程序、app、等不同业务线的接口,所以希望能支持下

  9. func (c *Cmd) Send(r *ghttp.Request) {}  格式的接口呢? 始终生成不了swagger 文档 ?????????
    1. 这种写法肯定是生不活的

      1. 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
        }



        1. g.Meta `path:"/" method:"get" summary:"接口是啥" tags:"我是哪个组的"` 这个要加个 tags, summary,看下文档

          还有,swagger要打开,openApi也可以打开

          1. 打开了~ 如示例的(只有一个 Say 函数的)可行。

            但是新增一个几乎同样的 SayHi,就不行了

            1. 同一个对象下面尝试注册多个方法为 handler,就是没成功~ 求个例子

                1. 看了一下,版本信息对上了,其他内容不是很对症

                  但,找到处理方法了(原因未知,也许和之前 1.6/2.x 混用有关)

    2. 我也想知道如何才能手动注册 openapi,还有生成的 openapi中的 omitempty 怎么去掉

  10. 这种命名的约定也是叫人很无奈。。。过度约束了

    invalid struct naming for response: defined as "%s", but it should be named with "Res" suffix like "XxxRes"
    1. 我觉得也是,不明白为什么要强制以Req和Res结尾

        1. 个人觉得框架不应该限制命名,这个应该团队来约定,框架做这些有些过度约束了,强迫症看了表示难受 (๑*◡*๑)

  11. 个人水平有限,感觉框架越来越复杂,看得越来越懵逼。

    1. 适配的场景越多,复杂性必然上升。

      好的框架,能隔离复杂场景和简单场景。

      gf 的成熟度还欠缺

      1. 如果有好的点,可以issue描述具体的case,可以一起参与完善,非常欢迎社区贡献。

    2. 规范路由是稍微复杂一点,本质其实就是结构化输入输出、通过标签来维护接口文档。

  12. 我是从codeigniter,到beego,现在来看goframe,用惯了beego的目录结构,现在来看goframe的是有些别扭。beego是注解路由文档。

    1. goframe的老版本也是用的注解,弊端挺多的,所以新版本就改为了结构化及标签形式的,具体介绍可以参考:路由注册-规范路由

  13. v标签生成 open api返回的数据和swagger-ui不兼容,如:get请求定义v:required,在swagger-ui内规则判断为输入框必须输入required这个单词,是否有解,还是只能用默认的redoc

  14. 请教下,按照以下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`
    1. 大概看了下源码,如果response添加了mime就会忽略CommonResponse。这应该不是规范方法,我是偷懒了,先用。希望能有个规范的方法。

  15. gf默认生成的是OpenAPI3协议的,可以降成2的吗?用openapi3协议的json文件再Yapi页面上导入的时候会报错

  16. 请问一下如何在规范路由模式下去掉默认添加的 bail 规则呀?,我想要拿到请求验证的所有错误而不是只有第一条,本来想不用规范路由直接来但是好像这样又不会自动生成 swagger