apidoc安装使用说明

一、apidoc简单介绍

          apidoc根据你源码中的api注解(apidoc自己的注解)，创建说明文档，创建出的说明文档为html格式，能够发布出去，apidoc是基于nodejs，代码开源，官网地址，github地址，目前最新提交是2017年5月，貌似已经停止维护，不过整个代码逻辑很简单，适合定制，apidoc基本支持所有语言的文档生成，C#、Java、JavaScript、PHP、Python，具体可参加官方说明

二、apidoc安装

     1.首先查看是否有nodejs环境，node -v ,查看node版本，如果不能执行，需要安装nodejs，nodejs下载地址https://nodejs.org/en/download/，可以根据具体环境选择版本，win可以下载压缩包，解压后，把解压文件夹的根目录配置到path里即可，linux一般都会自带nodejs,如果没有可yum install nodejs -y ,不同的linux版本使用不同的在线安装命令，这里列出CentOS，如果不能在线安装，那就只能自己下了，这里不在赘述

        2.安装完nodejs环境后，会自带npm,npm为nodejs包管理工具，安装apidoc :npm install apidoc -g, 安装完成后，使用apidoc -h,查看是否安装成功

三、apidoc使用

        1.添加apidoc.json

         在项目中创建apidoc.json,位置建议在项目根目录，也可自选，自选位置的话，需要在运行apidoc命令时带上位置参数

apidoc.json内容示例

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

各参数含义

参数	说明
name	项目名称
version	项目版本
description	项目描述
title	浏览器标题
url	api路径前缀，会自动拼接到@api 路径前，可以设置为空串
sampleUrl	如果设置，将显示用于测试api方法（发送请求）的表单。有关详细信息，请参阅@apiSampleRequest。
header	api文档的头
title	左侧导航栏中显示的文本
filename	内容文件，为md(markdown)格式，可以写前言等项目边角信息
footer	与header相同，只不过一个在头，一个在尾，不再赘述
title
filename
order	用于排序的，没有详细研究

  带header示例

{
  "name": "onsite接口说明文档", 
  "version": "1.0.0",
  "description": "",
  "title": "onsite接口说明文档",
  "url":"",
  
  "header": {
    "title": "My own header title",
    "filename": "api-template/header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "api-template/footer.md"
  }
}

          2.添加api注解

api注解是apidoc自己定义的一套，用于生成文档的注解，注解太多就不一一介绍了，大家可以参考官说明http://apidocjs.com/#param-api，这里仅说明基础使用.

apidoc是按注释块解析注解的，在java中一个注释块形如(以下为两个注解块)：

/**
 * @api {get} /user/{id}  获取用户信息
 */
/**
 * @api {put} /user/{id}  修改用户信息
 */

apidoc仅解析含有@api或者@apiDefine的注释块，@apiDefine一个注释块中仅能有一个，@apiDefine可以定义一些通用的内容，比如通用的请求参数，返回值，错误列表等 ；@api 就不用多说了，用来定义一个api,需要注意的是，@apiGroup和@apiName是必须的，@apiGroup定义的是左侧导航，@apiName 会拼接到访问路径中，大家试下就会明白

@apiGroup是不支持中文的，需要和@apiDefine配合使用，例如：

/**
 * @apiDefine User  用户模块
 *            
 */
/**
 * @api {get} /user/{id} 获取用户信息
 * @apiGroup User
 * @apiName Get-user
 * 
 */

以下为官网一个较为完整的例子

apidoc.json

{
  "name": "example-inherit",
  "version": "0.1.0",
  "description": "apiDoc inherit example"
}

example.js

/**
 * @apiDefine UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiUse UserNotFoundError
 */

/**
 * @api {put} /user/ Modify User information
 * @apiName PutUser
 * @apiGroup User
 *
 * @apiParam {Number} id          Users unique ID.
 * @apiParam {String} [firstname] Firstname of the User.
 * @apiParam {String} [lastname]  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 * @apiUse UserNotFoundError
 */

生成文档地址：http://apidocjs.com/example_inherit/#api-User

从例子可以看出，apidoc不在乎你把注释写在哪里，不过还是推荐写在接口所在位置

          3.执行apidoc命令

以上两步完成后，就可以执行apidoc命令生成文档了，打开命令行，切换到项目根目录，执行apidoc -f  "正则"  -i 输入路径  -o  文档输出路径 ，大家可以根据自己情况选取参数，执行apidoc -h 可列出各种参数用法以及默认值

参数	说明
-h，--help	显示帮助信息
-f，--file-filters	正则表达式过滤应该解析的文件（可以使用多个-f）。默认值：.cs .dart .erl .go .java .js .php .py .rb .ts。 示例（仅解析.js和.ts文件）： apidoc -f ".*\.js$" -f ".*\.ts$"
-e, --exclude-filters	正则排除不需要解析的文件，可是使用多个
-i, --input	项目源码根目录，默认值：./
-o, --output	生成文档输出位置，默认值：./doc
-t, --template	生成文档使用的模版位置，默认值：%apidoc%\template\,   %apidoc%为apidoc安装根目录
-c, --config	配置文件(apidoc.json)的所在位置，默认值：./

四、注意事项

        1.没有参数说明时，apidoc会扫描当前目录以及所有子目录下.cs .dart .erl .go.java .js .php .py .rb .ts结尾的文件，生成api文档到当前目录下doc文件夹中;

       2.apidoc -f后的正则表达式，标准格式".*\.java",eg:apidoc -f ".*\.java" ,必须使用双引号，并且单斜杠\,其他写法都会导致“No files found”;

        3.@apiDefine定义的内容貌似只能作为name参数使用，这个局限太大，api中很多路径前半段都是相同的，想抽象出来一个都不行，以后如果修改，比较麻烦，不知道大家有没有什么高招可以解决

        4.要写注解怎么能没有自动补全呢，java和php自动补全：Java Eclipse ,PHP Eclipse，官方文档说的很清楚了