一、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浏览器标题urlapi路径前缀，会自动拼接到@api 路径前，可以设置为空串sampleUrl如果设置，将显示用于测试api方法（发送请求）的表单。有关详细信息，请参阅@apiSampleRequest。headerapi文档的头 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，官方文档说的很清楚了
————————————————
版权声明：本文为CSDN博主「椰汁菠萝」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/suo082407128/article/details/81355093
