接口文档神器apidoc

1、apidoc介绍

1、apidoc是什么？

api文档生成工具：基于源代码备注创建的接口文档；

2、apidoc优势是啥？

超简单文档生成器：几乎支持目前主流的所有风格的注释， 如可在C#、Go、python、Java、JavaScript、PHP等语言中使用。 便于管理和查看：有利于代码的阅读同时，也减轻文档编写工作。

3、apidoc官网：

https://apidocjs.com/

2、安装使用

2.1、windows系统安装

1、安装nodejs（nodejs环境）：

• 32 位安装包下载地址 : https://nodejs.org/dist/v4.4.3/node-v4.4.3-x86.msi
• 64 位安装包下载地址 : https://nodejs.org/dist/v4.4.3/node-v4.4.3-x64.msi

2、安装apidoc 命令：npm install apidoc -g

3、查看ApiDoc是否安装成功 命令：apidoc -v 

注：npm是什么？

NPM 名字的由来：Node Package(包) Manager(管理器) 与Node.js的关系：发展相辅相成，最终 Node.js 内置了npm。

2.2、linux版安装(ubuntu)

1、更新ubuntu软件源

2、安装nodejs

3、更新npm包镜像源

4、全局安装npm管理器（用于管理nodejs版本）

5、安装最新的nodejs

6、安装apidoc 命令：sudo npm install apidoc -g

3、apidoc使用

3.1、常用语法

可参考：https://apidocjs.com/ 

 

3.2、接口文档运用

组成：json+文档脚本

配置(apidoc.json)： 主要包含描述信息，比如标题、描述、版本、排序等； 可加入可选配置项，如页眉/页脚(markdown)、模板等； 字段内容支持html格式（如描述）。

文档脚本： 需遵循语言注释格式，除必填字段外，其它字段可根据实际情况使用。

3.3、apidoc导出成html

运行命令：apidoc -i src -o apidoc ，详细的字段说明如下：

举例：如要将放在E:\apidoc\convert的apidoc.json转换成html放在E:\apidoc\convert_result路径下

命令：apidoc -i E:\apidoc\convert -o E:\apidoc\convert_result

 访问：E:\apidoc\convert_result路径下生成的html文件，一份完整的接口文档生产出来啦！