【go语言微服务实践】#4-beego和go-micro自动化生成API文档

线上答题系统，微服务架构的小小实践，项目代码

一、概述

  单体应用在改造成微服务架构后，模块与模块间的交互会变得复杂，功能增多，接口也会增多，因此十分有必要维护一份系统的API接口说明。答题系统从上到下分为view、controller、service、model四层，controller和前端view之间使用REST API交互，因此使用目前比较流行的swagger进行接口维护。controller和service之间是RPC接口，使用的是protocol buffers协议，可以使用protoc-gen-doc工具直接生成rpc接口说明的html页面。

技术选型
前端view层：planeui+jquery
controller层（页面逻辑处理）：beego
service层：go-micro
model层：beego的orm
REST API展示：swagger
RPC API展示：protoc-gen-doc

二、beego与swagger

  Beego支持自动化生成swagger API文档，只需要按语法规则在routers/router.go中配置好路由 ，并在对应的cotroller方法写好路由注释。以用户的CURD为例：

1. 全局路由配置

  在routers/router.go最顶部注释

// @APIVersion 1.0.0
// @Title mobile API
// @Description mobile has every tool to get any job done, so codename for the new mobile APIs.
// @Contact astaxie@gmail.com
package routers

  目前自动化文档只支持如下的写法的解析，其他写法函数不会自动解析，即 namespace+Include 的写法，而且只支持二级解析，一级版本号，二级分别表示应用模块。因此/v1/users的请求对应UserManageController。

func init() {
   ns :=
      beego.NewNamespace("/v1",
         beego.NSNamespace("/users",
            beego.NSInclude(