1. API自动化文档

自动化文档一直是我梦想中的一个功能，这次借着公司的项目终于实现了出来，我说过 beego 不仅仅要让开发 API 快，而且让使用 API 的用户也能快速的使用我们开发的 API，这个就是我开发这个项目的初衷。好了，赶紧动手实践一把吧，首先新建一个 API 应用做起来吧。

2. API 全局设置

必须设置在 routers/router.go 中，文件的注释，最顶部：

全局的注释如上所示，是显示给全局应用的设置信息，有如下这些设置

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

接下来就是我们最重要的注释了，就是我们定义的，我们先来看一个例子：

首先是 CMSController 定义上面的注释，这个是用来显示这个模块的作用。接下来就是每一个函数上面的注释，这里列出来支持的各种注释：

参数名
参数类型，可以有的值是 formData、query、path、body、header，formData 表示是 post 请求的数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body 表示是一个 raw 数据请求，header 表示带在 header 信息中得参数。
参数类型
是否必须

@Success

成功返回给客户端的信息，三个参数，第一个是 status code。第二个参数是返回的类型，必须使用 {} 包含，第三个是返回的对象或者字符串信息，如果是 {object} 类型，那么 bee 工具在生成 docs 的时候会扫描对应的对象，这里填写的是想对你项目的目录名和对象，例如 models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的对象。

失败返回的信息，包含两个参数，使用空格分隔，第一个表示 status code，第二个表示错误信息
@router

路由信息，包含两个参数，使用空格分隔，第一个是请求的路由地址，支持正则和自定义路由，和之前的路由规则一样，第二个参数是支持的请求方法,放在 [] 之中，如果有多个方法，那么使用 , 分隔。

要使得文档工作，你需要做几个事情，

第一开启应用内文档开关，在配置文件中设置：EnableDocs = true,
然后在你的函数中引入 _ "beeapi/docs"（beego 1.7.0 之后版本不需要添加该引用）。
这样你就已经内置了 docs 在你的 API 应用中，然后你就使用 bee run -gendoc=true -downdoc=true,让我们的 API 应用跑起来，-gendoc=true 表示每次自动化的 build 文档，就会自动的下载 swagger 文档查看器

好了，现在打开你的浏览器查看一下效果，是不是已经完美了。下面是我的 API 文档效果：

API自动化文档 - 图1