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