4.3 Swagger2.0在线API文档

API文档信息可以从两个地方获取，一个是struct Handler的字段标签中定义，一个是通过实现APIHandler接口来定义。

APIHandler接口定义的相关源码：

  1. type (
  2.     // Handler is the main Faygo Handler interface.
  3.     Handler interface {
  4.         Serve(ctx *Context) error
  5.     }
  6.     // APIHandler is the Faygo Handler interface,
  7.     // which is implemented by a struct with API descriptor information.
  8.     // It is an intelligent Handler of binding parameters.
  9.     APIHandler interface {
  10.         Handler
  11.         APIDoc
  12.     }
  13.     // APIDoc provides the API's note, result or parameters information.
  14.     APIDoc interface {
  15.         Doc() Doc
  16.     }
  17.     // Doc api information
  18.     Doc struct {
  19.         Note   string      `json:"note" xml:"note"`
  20.         Return interface{} `json:"return,omitempty" xml:"return,omitempty"`
  21.         Params []ParamInfo `json:"params,omitempty" xml:"params,omitempty"`
  22.     }
  23.     // Notes implementation notes of a response
  24.     Notes struct {
  25.         Note   string      `json:"note" xml:"note"`
  26.         Return interface{} `json:"return,omitempty" xml:"return,omitempty"`
  27.     }
  28.     // ParamInfo is the request parameter information
  29.     ParamInfo struct {
  30.         Name     string      // Parameter name
  31.         In       string      // The position of the parameter
  32.         Required bool        // Is a required parameter
  33.         Model    interface{} // A parameter value that is used to infer a value type and as a default value
  34.         Desc     string      // Description
  35.     }
  36. )

4.3.1 函数类型Handler定义API信息

通过使用函数faygo.WrapDoc()封装，为func Handler添加API文档信息，得到满足APIHandler接口的对象：

  1. // 参数fn为预增加API信息的Handler函数，
  2. // 参数note是API接口说明，
  3. // 参数ret为API返回结果示例，
  4. // 不定参parms为API请求参数信息
  5. func WrapDoc(fn HandlerFunc, note string, ret interface{}, params ...ParamInfo) Handler

示例：

  1. var AdditionHandler = faygo.WrapDoc(
  2.     // Handler
  3.     faygo.HandlerFunc(func(ctx *faygo.Context) error {
  4.         // 获取请求参数，并作类型转换
  5.         var a, b int
  6.         if err := ctx.BindBizParam(&a, "the_one"); err != nil {
  7.             return err
  8.         }
  9.         if a < 0 || a > 100 {
  10.             return ctx.String(406, "参数 the_one 超出 [0,10] 的范围")
  11.         }
  12.         if err := ctx.BindBizParam(&b, "other"); err != nil {
  13.             return err
  14.         }
  15.         return ctx.String(200, "(%s) + (%s) = %d", ctx.QueryParam("the_one"), ctx.QueryParam("other"), a+b)
  16.     }),
  17.     // API接口说明
  18.     "addition",
  19.     // 响应说明或示例
  20.     "返回文本格式的处理结果",
  21.     // 定义参数
  22.     faygo.ParamInfo{
  23.         Name:     "the_one",
  24.         In:       "query",
  25.         Required: true,
  26.         Model:    int(2), // API文档中显示的参数默认值
  27.         Desc:     "plus number, range: [0,100]",
  28.     },
  29.     faygo.ParamInfo{
  30.         Name:     "other",
  31.         In:       "query",
  32.         Required: true,
  33.         Model:    int(-1), // API文档中显示的参数默认值
  34.         Desc:     "other plus number",
  35.     },
  36. )

运行服务后打开API在线文档：

  1. http://localhost:8080/apidoc

测试该API接口：

apidoc func addition

4.3.2 结构体类型Handler定义API信息

struct Handler的API信息涉及到两个地方：

  • 结构体字段的标签，既用于绑定验证参数，也用于API信息的生成
  • 通过定义Doc方法实现APIHandler接口，在字段标签信息的基础上对API信息进行补充

将4.3.1中func Handler改写成struct Handler：

  1. type Addition struct {
  2.     // <in:query> 定义query类型请求参数；
  3.     // 参数名为字段名转为默认的snake格式（默认格式可自定义），即'the_one'；
  4.     // 该参数值会被自动转为int类型；
  5.     // <range: 0:100> 当其大小不在[0,100]范围时，faygo自动返回错误，错误模板可以自定义；
  6.     // <desc:plus number> 定义参数描述为'plus number'
  7.     TheOne int `param:"<in:query> <desc:plus number> <range: 0:100>"`
  8. }
  10. // 实现Handler接口
  11. func (a *Addition) Serve(ctx *faygo.Context) error {
  12.     var b int
  13.     if err := ctx.BindBizParam(&b, "other"); err != nil {
  14.         return err
  15.     }
  16.     return ctx.String(200, "(%d) + (%s) = %d", a.TheOne, ctx.QueryParam("other"), a.TheOne+b)
  17. }
  19. // 补充API文档信息
  20. func (a *Addition) Doc() faygo.Doc {
  21.     return faygo.Doc{
  22.         // API接口说明
  23.         Note: "addition",
  24.         // 响应说明或示例
  25.         Return: "返回文本格式的处理结果",
  26.         // 补充参数定义
  27.         Params: []faygo.ParamInfo{
  28.             {
  29.                 Name:     "other",
  30.                 In:       "query",
  31.                 Required: true,
  32.                 Model:    int(-1),
  33.                 Desc:     "other plus number",
  34.             },
  35.         },
  36.     }
  37. }

该示例不仅展示了如何通过定义Doc方法扩展API的非参数信息，更特意展示了在Doc方法中补充参数信息（实际应用中很少见）。

该Handler的功能与4.3.1中AdditionHandler完全相同。但是为了使API文档中请求参数the_one默认值也相同，在定义路由时，应该使用实例 &Addition{TheOne: 2} 来指定the_one默认值。这里仅展示定义该路由的代码片段，路由详细用法将在第5章中讲述。

  1. frame.NewNamedAPI("addition", "GET", "/addition", &Addition{TheOne: 2})

4.3.3 相关ini配置

Swagger2.0 API在线文档的默认访问路径为 /apidoc，其配置信息在相应Web服务的ini配置文件中（文件名格式 config/{appname}[_{version}].ini），apidoc的配置详情：

  1. [apidoc]                                         # API文档
  2. enable      = true                               # 是否启用
  3. path        = /apidoc                            # 访问的URL路径
  4. nolimit     = false                              # 是否不限访问IP
  5. real_ip     = false                              # 使用真实客户端的IP进行过滤
  6. whitelist   = 192.*|202.122.246.170              # 表示允许带有`192.`前缀或等于`202.122.246.170`的IP访问
  7. desc        =                                    # 项目描述
  8. email       =                                    # 联系人邮箱
  9. terms_url   =                                    # 服务条款URL
  10. license     =                                    # 协议类型
  11. license_url =                                    # 协议内容URL