apidoc安装使用说明

本文主要是介绍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)的所在位置，默认值：./