revel + swagger 文档也能互动啦

beego 从 1.3 后开始支持自动化API文档，不过，目测比较复杂，一直期望 revel 能有官方支持。

revel 确实已经有了官方支持的计划，有可能将在 0.14 版本支持，现在才 0.11.1 版本，只好自己手工撸一个出来，半自动化，但能满足基本需求了。

1. 准备

1.1 swagger-ui

swagger 是一个开源项目，swagger-ui 将符合 swagger 定义的描述规则的 Json 数据以网页形式呈现。

swagger 有在线的实例可以直接看到 swagger-ui 文档效果，如下：

swagger-ui 本身是不需要依赖任何第三方代码的，而使用 swagger-ui 实现 revel 的 API 文档仅需 swagger-ui 源码 dist 文件夹中的文件，可以如下获取：

git clone https://github.com/swagger-api/swagger-ui

然后，将 dist 路径下文件拷贝到工程目录（目录结构见下文）。

1.2 代码生成

swagger 有专门的代码生成项目 swagger-codegen，但别着急，revel 需要的不是它，是在 swagger-spec 发现的 Swagger spec generator，golang 实现、自带 swagger-ui。

go get github.com/yvasiyarov/swagger

直接命令行输入swagger 回车

支持三个级别注释：

General API info, API 通用信息，在项目入口函数所在文件写一份即可，例如 init.go

// @APIVersion 1.0.0

// @Title My Cool API

// @Description My API usually works as expected. But sometimes its not true

// @Contact api@contact.me

// @TermsOfServiceUrl http://google.com/

// @License BSD

// @LicenseUrl http://opensource.org/licenses/BSD-2-Clause
Sub API Definitions, 子模块定义，每个资源定义一次

// @SubApi Order management API [/order]

// @SubApi Statistic gathering API [/cache-stats]
API Operation, API 定义，需要文档化的接口函数

// @Title getOrdersByCustomer

// @Description retrieves orders for given customer defined by customer ID

// @Accept json

// @Param customer_id path int true "Customer ID"

// @Param order_id query int false "Retrieve order with given ID only"

// @Param order_nr query string false "Retrieve order with given number only"

// @Param created_from query string false "Date-time string, MySQL format. If specified, API will retrieve orders that were created starting from created_from"

// @Param created_to query string false "Date-time string, MySQL format. If specified, API will retrieve orders that were created before created_to"

// @Success 200 {array} my_api.model.OrderRow

// @Failure 400 {object} my_api.ErrorResponse Customer ID must be specified

// @Resource /order

// @Router /orders/by-customer/{customer_id} [get]

1.3 revel module

revel 支持模块，每个模块可以有独立的路由和配置文件，即 routes.go 和 app.conf，revel 负责将其与其他模块及主应用对应文件合并，详细规则可参考 revel 文档相关章节 Modules。

swagger-ui 将以 revel module 方式插入主应用，需要设计独立的路由。

1.4 目录结构

revel new revel-swagger

新建 modules 文件夹，并在其中建立 swagger-ui 文件夹，如下：

2 实现

2.1 Step 1

复制 yvasiyarov/swagger/swagger-ui/ 路径下文件至 revel-swagger/modules/swagger/swagger-ui
在 revel-swagger/modules/swagger/conf 新建 routes 文件，放入如下路由

GET /docs Docs.GetApiDocs

GET /docs/api/*filepath Static.ServeModule("swagger","swagger-ui")

GET /docs/:apiKey Docs.GetApiDoc
在 revel-swagger/modules/swagger/app/controllers 新建 apidocs.go 并实现 routes 中定义的路由

2.2 Step 2

在主应用 app.conf 文件中添加模块引用 module.swagger = you/path/to/revel-swagger/modules/swagger
在主应用 routes 文件中添加模块路由 module:swagger

2.3 Step 3

使用 github.com/yvasiyarov/swagger 生成 swagger 支持的 Json 注释文件 docs.go
- -apiPackage 设置为主应用 app/controllers 路径，路径为相对于 $GOPATH/src 的相对路径
- -mainApiFile 设置为主应用的某个 .go 文件路径，作为 swagger 通用 API 信息定义文件，同样路径为相对 $GOPATH/src 的路径
- -output 输出路径，设置为 you/path/to/revel-swagger/modules/swagger/app/controllers，为绝对路径

在 you/path/to/revel-swagger/modules/swagger/app/controllers 生成了 docs.go 文件，此时，访问 localhost 就可以看到 swagger-ui 页面了，不过内容还是 swagger 的示例。

2.4 Step 4

init.go 添加 General API info
app.go 添加 API 接口及注释
修改 swager-ui/index.html 第 28 行为 url: "http://127.0.0.1:9000/docs"
重新生成 docs.go
- 设置 -basePath=127.0.0.1:9000

访问 http://127.0.0.1:9000 可以看到 API 的 swagger 文档了：

3 其他

yvasiyarov/swagger 支持的数据格式需要参考其项目说明
- 没有找到上传文件及参数为数组的描述方法，swagger 本身是支持的
示例代码放在 github