配置文件

这里使用YAML配置文件:config.yaml

  1. server:
  2. address: ":8199"
  3. openapiPath: "/api.json"
  4. swaggerPath: "/swagger"

示例代码

我们从一个简单的Hello例子开始:

  1. package main
  2. import (
  3. "context"
  4. "fmt"
  5. "github.com/gogf/gf/v2/frame/g"
  6. "github.com/gogf/gf/v2/net/ghttp"
  7. )
  8. type HelloReq struct {
  9. g.Meta `path:"/hello" method:"get"`
  10. Name string `v:"required" dc:"Your name"`
  11. }
  12. type HelloRes struct {
  13. Reply string `dc:"Reply content"`
  14. }
  15. type Hello struct{}
  16. func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) {
  17. g.Log().Debugf(ctx, `receive say: %+v`, req)
  18. res = &HelloRes{
  19. Reply: fmt.Sprintf(`Hi %s`, req.Name),
  20. }
  21. return
  22. }
  23. func main() {
  24. s := g.Server()
  25. s.Use(ghttp.MiddlewareHandlerResponse)
  26. s.Group("/", func(group *ghttp.RouterGroup) {
  27. group.Bind(
  28. new(Hello),
  29. )
  30. })
  31. s.Run()
  32. }

拷贝这段代码,我们运行起来试试,终端输出信息如下:

  1. 2021-11-19 23:31:35.277 25580: http server started listening on [:8199]
  2. SERVER | DOMAIN | ADDRESS | METHOD | ROUTE | HANDLER | MIDDLEWARE
  3. ----------|---------|---------|--------|------------|-----------------------------------------------------------|--------------------
  4. default | default | :8199 | ALL | /* | github.com/gogf/gf/v2/net/ghttp.MiddlewareHandlerResponse | GLOBAL MIDDLEWARE
  5. ----------|---------|---------|--------|------------|-----------------------------------------------------------|--------------------
  6. default | default | :8199 | ALL | /api.json | github.com/gogf/gf/v2/net/ghttp.(*Server).openapiSpec-fm |
  7. ----------|---------|---------|--------|------------|-----------------------------------------------------------|--------------------
  8. default | default | :8199 | GET | /hello | main.(*Hello).Say |
  9. ----------|---------|---------|--------|------------|-----------------------------------------------------------|--------------------
  10. default | default | :8199 | ALL | /swagger/* | github.com/gogf/gf/v2/net/ghttp.(*Server).swaggerUI-fm | HOOK_BEFORE_SERVE
  11. ----------|---------|---------|--------|------------|-----------------------------------------------------------|--------------------

可以看到,除了我们的业务路由之外,Server自动帮我们注册了两个路由:/api.json/swagger/*。前者是自动生成的基于标准的OpenAPIv3协议的接口文档,后者是自动生成SwaggerUI页面,方便开发者查看和调试。这两个功能默认是关闭的,开发者可以通过前面示例中的openapiPathswaggerPath两个配置项开启。

接口文档

接口文档通过OpenAPIv3协议生成,一般来说需要结合相应的UI工具查看,地址:http://127.0.0.1:8199/api.json

由于OpenAPIv3协议是规范的接口定义协议,因此开发者根据协议内容可以做很多事,例如:自定义UI展示、Client代码生成、协议转换等等。

SwaggerUI

我们来看看这个SwaggerUI页面:http://127.0.0.1:8199/swagger/

规范路由-基本示例 - 图1

这里只有一个我们的路由地址以及对应的输入输出结构体。当然,这只是个简单的示例,你可以在真实的项目中通过一些配置使得页面更加丰富多彩。

我们接着在这个页面上做下接口测试吧:

规范路由-基本示例 - 图2

嗯,接口返回了一个固定数据格式的Json内容,但是能看到其中的data为我们需要的返回结果。

提示:最新版本的SwaggerUI页面已经不支持接口测试功能,如果对此有要求的同学可以自定义SwaggerUI(参考接口文档-自定义UI), 也可以导入接口文件api.json 到第三方工具(例如 apifox)进行测试:

规范路由-基本示例 - 图3

返回中间件

等等,似乎漏掉了什么东西?是的,我们这里使用了一个Server组件提供的中间件,它是拿来做什么的呢?我们开看看它的方法定义:

规范路由-基本示例 - 图4

是的,它在我们没有提供自定义的返回数据格式处理中间件时,使用了一个默认的中间件处理我们的请求,并返回了一个默认的数据格式。