百家饭OpenAPI v0.6.0新版夏日发布！快来看（1）——好用的Golang swagger文档生成工具

    百家饭OpenAPI工具更新到了v0.6.0版本，带来了全新的API工作台和配套的客户端工具，本周我们将分篇介绍v0.6.0版本的各项更新功能，

1. 0.6.0版本里面的Golang swag工具！
2. API文档的编辑与共享
3. API在线测试
4. API JS代码自动生成
5. API模拟与远程调试

集成Swag命令说明

从0.6.0版本开始，百家饭OpenAPI命令行工具整合开源swag命令，用于Golang语言的swag文档生成。0.6版本的客户端已经开放下载，集成版本为百家饭团队在原始版本上扩展的版本。原始版本的介绍，大家可以查看我们原来的介绍文章，或者打开原版本主页浏览功能介绍文章，在原版的基础上，百家饭的版本提供了更多的功能扩展，主要区别如下：

支持多路径声明

原始版本中，对于一个入口Controller函数，虽然可以声明不同的路径，但是每个路径对应的入参和出参要求只能定义为一份。但是实际工作中，我们针对一个固定的url，例如rongapi.cn/api/123.json，我们常见的操作是使用GET进行读取操作，使用Post进行更新操作，这也是符合RESTful规范的一种用法。因此，我们扩展了swag的指令，使其支持针对单一入口定义多种入参和出参要求，例如：

// Function1
// @Tags        api
// @Param       id  path     int      true  "单次获取个数"
// @Param       Type path string true "返回数据的类型，json/xml" default(json)
// @Produce     json
// @Router      /api/function1/{id}/{typ}.{Type} [get]
// @Param       typ   path     string  true  "操作类型，获取，创建，更新还是删除" enums(get)
// @Summary     获得一个接口的所有模拟调用配置
// @Description 获得一个接口的所有模拟调用配置
// @Accept      x-www-form-urlencoded
// @Success     200    {array}   model.Source
// @Failure     default {object} errors.Error
// @Router      /api/function1/{id}/{typ}.{Type} [post]
// @Summary     对某个id的接口的配置进行更新操作
// @Description     对某个id的接口的配置进行更新操作
// @Param       typ   path     string  true  "操作类型，获取，创建，更新还是删除" 
// @Param       emulation body model.Emulation true "创建或提交的配置，用于删除时不需要提交"
// @Accept      json
// @Success     200    {object}   {Success=bool}
func (o *Openapi) Function1(id string, typ string, ctx *goblet.Context) error {

在这个标准的swag注释中，第6行和第13行，我们分别定义了两个不同的Url，唯一区别是一个是GET,一个是POST，通过这两行定义，整体定义被分成了三个部分。

1. 第一个部分（1-5行），此时，没有定义任意的url之前的部分，是该函数对应所有url的公有定义部分，会被不同的url定义所共享

2. 第二个部分（7-12行），是第6行定义的url所对应的特殊声明

3. 第二个部分（14-19行），是第13行定义的url所对应的特殊声明

第一个部分作为公共定义，会被两个url定义的入口共享，如果url定义的特殊部分对该部分有重复声明的属性，会被覆盖。

新增日志级别——Trace

原有的swag的日志级别只有Info和debug两个级别，我们初期使用swag的时候就遇到很多次错误没有头绪，只能看代码分析的情况，因此，我们利用logrus将原有仓库的日志级别进行了扩展，将原有的info和debug对应到了logrus的info和logrus的debug两级，并利用logrus的trace级别增加了更详细的日志内容输出。使用时，可以附加-v或者--verbose参数打开该级别日志输出。

同时，在该级别，我们为我们遇到的一些出错情况，附加了更为详细的错误情况说明，、同时为swag的init指令增加了过程中的流程细节输出，方便了解过程，方便我们对照错误改进注释的写法。

扩展返回的类型定义方法

在使用swag的过程中，我们发现，swag命令可以解析指定的Go定义数据类型作为返回内容（如上文例子中所使用的model.Source)，但是在实际定义中，我们有时并不会将所有的内容进行返回，我们自己的Goblet库就有RespondField()函数，可以指定返回一个结构体或结构体数组中的某一些特定属性，而屏蔽其他属性。因此，我们为swag增加了类似下面的写法：

// @Success     200    {object}   {Success=bool}

其中最后一个部分定义了一个自定义interface类型，其包含一个名为Success的bool类型属性，只需像Interface一样，用{}进行标注，里面用名称=类型，逗号分隔的形式定义一个或多个属性即可。

支持非命名类库引用

大家知道，Golang里面引用库通常的方式是

import (
  "rongapi.cn/api/model"
)

而golang会自动使用该引用库的package名称作为他的引用名称。

但原版swag并不支持这种模式的引用，需要使用如下形式：

import (
  model "rongapi.cn/api/model"
)

百家饭分发的swag修正了上述问题

安装和使用

上述版本的swag我们已经集成到了百家饭客户端中，可以下载使用。

当然，你也可以使用go命令安装

go install github.com/extrame/swag

上述修正我们也正在逐步提交给原始仓库，提交因为只能顺序提交，因为要一个issue对应一个提交，完成了，我们才好去提下一个，这使得我们维护一个可提交版本的时间线变得和我们的正常更新有些冲突，只能说慢慢做着吧。