APIDOC3.0

关于

apidoc 是一个简单的 RESTful API 文档生成工具,它从代码注释中提取特定格式的内容,生成文档。目前已支持以下语言:C#、C/C++、D、Erlang、Go、Groovy、Java、Javascript、Pascal/Delphi、Perl、PHP、Python、Rust、Ruby、Scala 和 Swift。

apidoc 拥有以下特点:

  1. 跨平台,linux、windows、macOS 等都支持;
  2. 支持语言广泛,即使是不支持,也很方便扩展;
  3. 支持多个不同语言的多个项目生成一份文档;
  4. 输出模板可自定义;

以下是一段简短的 Go 代码下的示例:

                /**
                 * @api get /users/:id 获取指定用户的相关信息
                 * @apiGroup users
                 * @apiParam id int 表示用户 id 的唯一值
                 *
                 * @apiSuccess 200 json ok
                 * @apiExample
                 * {"id":1, "name": "n1"}
                 */
                

多行注释中,每一行中以空白字符+symbol+空白字符开头的,这些字符将会被过滤,symbol 表示该注释块的起始字符中的任意字符。比如以上代码中,所有的 * 将被过滤。

使用

安装

若是你已经有 Go 开发环境,则可以直接通过 go get 来获取代码并安装:go get github.com/caixw/apidoc

环境变量

apidoc 会读取 LANG 的环境变量作为其本地化的依据,若想指定其它语种,可以手动指定 LANG 环境变量:LANG=cmn-Hant apidoc。在 windows 系统中,若不存在 LANG 环境变量,则会调用 GetUserDefaultLocaleName 函数来获取相应的语言信息。

命令行参数

参数描述
-h显示帮助信息
-v显示版本信息
-l列出当前支持的语言
-g在当前目录下创建配置文件模板
-pprof指定个性能测试项,目前支持 cpumem 两个选项

配置文件

apidoc 通过工作目录下的配置文件来控制其行为。文件名称固定为 .apidoc.json。以下为 .apidoc.json 的一个示例。

                    {
                        "version": "3.0.52.160529",
                        "inputs": [
                            {
                                "lang": "go",
                                "dir": "./",
                                "recursive": true
                            }
                        ],
                        "output": {
                            "dir": "./output/doc",
                            "type": "html",
                            "template":"",
                            "port":":9999"
                        }
                    }
                    
名称类型描述
version string 产生此配置文件的 apidoc 版本号
inputs array 指定输入的数据
    dir string 需要解析的源文件所在目录
    recursive bool 是否解析子目录下的源文件
    lang string 源文件类型。具体支持的类型可通过 -l 参数进行查找
output object 控制输出行为
    dir string 指定文档的保存目录
    type string 渲染类型,目前支持 htmlhtml+json 三种类型
    template string 模板所在路径,当渲染类型为 htmlhtml+ 时可用。
    port string 指定一个访问端口,当渲染类型为 html+ 时,必须指定此值。

inputs 为一个对象数组,每个数组元素可以指定一个独立项目。不过不支持同一项目下多语言的解析。

使用

运行 apidoc 时,程序会从当前的工作目录中查找 .apidoc.json 文件,并将其当作配置文件来执行相应操作。

apidoc -g 会为你产生一个默认的 .apidoc.json 配置文件。

示例

这里是一段简单的示例代码 ./example

自定义模板

在输出类型为 html 时,可以通过在配置文件 .apidoc.json 中的 template 参数指定自定义模板,只会分析模板当前目录下的 *.html 文件,其它文件将被忽略。

模板格式采用的是 Go 标准库的 html/template,系统会调用 groupindex 两个子模板,具体的可用数据可参考源码目录下的 output/static 下的模板。

html+html 的增强模式,在该模式下不会输出任何文件内容,而是可以直接在浏览器访问相关页面,方便调试模板页面。

文档

在 apidoc 中,标签存在一定的从属关系,下文中均会注明所有标签的父标或及子标签。判断一个标签属于哪个父标签,只需要根据当前标签往前查找,直到找到可作为该标签的父标签的标签即可。

@apidoc

@apidoc 用于指定一些全局性的设定,本身带一个标题属性,整个文档中只能出现一次。子元素有: @apiVersion@apiBaseURL@apiLicense@apiContent

语法:@apidoc title

参数必填说明
titletrue文档的标题,到行尾

示例:

                    /**
                     * @apidoc title of doc
                     * @apiVersion 2.0
                     * @apiBaseURL https://api.caixw.io
                     * @apiLicense MIT https://opensource.org/licenses/MIT
                     * @apiContent
                     * <p>这里可以是html</p>
                     * <p>会被原样输出</p>
                     */
                    

@apiVerson

用于指定文档的版本号。父标签:@apidoc

语法:@apiVersion version

参数必填说明
title true 文档的版本号,可以是任何字符串形式的内容

@apiBaseURL

用于指定文档所有地址的一个公共前缀。父标签:@apidoc

语法:@apiBaseURL url

参数必填说明
urltrue一般为一个 URL

@apiLicense

用于指定文档的版权信息。父标签:@apidoc

语法:@apiLicense name url

参数必填说明
nametrue版权的名称
urlfalse版权的详细文本地址

@apiContent

文档首页的一些介绍性内容,该内容将会被原样输出。父标签:@apidoc

语法:@apiContent content

参数必填说明
contenttrue多行字符串,一直到文档结尾,换行符会被转换成 <br>,其它内容原样输出

@api

指定一个 api 文档的内容,这是除 @apidoc 之外的另一顶级标签。子标签包括: @apiGroup@apiIgnore@apiQuery@apiParam@apiRequest@apiSuccess@apiError

语法:@api method url summary [\n detail]

参数必填参数说明
methodtrue该 api 对应的请求方法
urltrue该 api 的请求地址
summarytrue该 api 的简要描述信息,到行尾结束
detail false api 的详细信息,可以多行,直到碰到以 @api 开头的行

示例:

                    /**
                     * @api get /users/{id} 获取指定用户的相关信息
                     * @apiGroup users
                     */
                    

@apiIgnore

凡是带此标签的代码块,表示该文档暂时被忽略。父标签:@api

语法:@apiIgnore

@apiGroup

@apiGroup 提供了对 api 的分组信息,不同的分组,最终可能会被呈现在不同的页面。父标签:@api

若要将文档显示在首页,则不需要指定此标签或是指定为 index

语法:@apiGroup name

参数必填描述
nametrue分组名称,相同名称不同大小写,将会被分配到同一个分组,但名称上依旧区分大小写。

@apiQuery

@apiQuery 描述 api 的查询参数。父标签:@api

语法:@apiQuery name type summary

参数必填描述
nametrue参数名称
typetrue参数的类型
summarytrue一行简短的语名用于描述该参数作用。

示例:

                    /**
                     * @api get /users 获取所有的用户信息。
                     * @apiQuery page int 获取第几页的内容。
                     * @apiQuery size int 每页显示的数量,必须大于 0。
                     */
                    

@apiHeader

@apiHeader 用于指定报头内容。父标签: @apiRequest@apiSuccess@apiError

语法:@apiHeader key summary

参数必填描述
keytrue报头名称
summarytrue到行尾,对此报头的描述。

示例:

                    /**
                     * @api delete /users/login 注销用户
                     * @apiHeader Authorization Basic xx-af
                     */
                    

@apiParam

@apiParam 用于描述参数信息。父标签: @api@apiRequest@apiSuccess@apiError

语法:@apiParam name type summary

参数必填描述
nametrue参数名称
typetrue参数的类型
summarytrue一行简短的语名用于描述该参数作用。

示例-1:

                    /**
                     * @api get /users/{id} 获取所有的用户信息。
                     * @apiParam id int 用户 id
                     *
                     * @apiSuccess 200 OK
                     * @apiParam id    int    用户 id
                     * @apiParam name  string 用户名称
                     * @apiParam group id     用户所属组 id
                     */
                    

示例-2:

                    /**
                     * @api post /users/ 新增用户
                     * @apiGroup users
                     *
                     * @apiRequest json
                     * @apiParam name     string 用户名称
                     * @apiParam password string 密码
                     *
                     * @apiSuccess 200 OK
                     * @apiHeader location xxxx
                     */
                    

@apiExample

指定示例代码。父标签: @apiRequest@apiSuccess@apiError

语法:@apiExample type

参数必填描述
typetrue示例代码的语言类型,默认模板在联网状态下会调用 prismjs 为示例代码着色

示例:

                    /**
                     * @apiExample json
                     * { "id":1, "name":"admin" }
                     */
                    

@apiRequest

@apiRequest 描述了所有的请求该包含的内容,其本身可包含 @apiHeader@apiExample@apiParam 三个子标签。父标签:@api

语法:@apiRequest type

参数必填描述
typetrue请求的数据类型

示例:

                    /**
                     * @apiRequest json
                     * @apiHeader Authorization Basic xxxx
                     * @apiParam username string 登录账号
                     * @apiParam password string 登录密码
                     * @apiExample json
                     * {"username":"admin", "password":"123"}
                     */
                    

@apiSuccess

@apiSuccess 描述了成功响应时包含的内容,其本身可包含 @apiHeader@apiExample@apiParam 三个子标签。父标签:@api

语法:@apiSuccess status summary

参数必填描述
statustrue返回的状态码
summarytrue一个简短的描述信息。

示例:

                    /**
                     * @apiSuccess 200 OK
                     * @apiHeader Authorization Basic xxxx
                     * @apiParam username string 登录账号
                     * @apiParam name string 用户名称
                     * @apiParam sex string 用户性别
                     * @apiExample json
                     * {"username":"admin", "name":"admin", "sex":"male"}
                     */
                    

@apiError

@apiError 结构与 @apiSuccess 完全相同,只是一个用于描述错误时的返回,一个用于描述成功时的返回信息。