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 infoapp.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