Ubuntu安装apiDoc以及入门教程

本文主要是介绍Ubuntu安装apiDoc以及入门教程，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

一.apiDoc简介

apiDoc是用来生成RESTful风格Web API文档的工具，支持现在流行的大部分编程语言，如Python,Java,C#, Go, Dart, Java, JavaScript, PHP, Scala 等。在源代码的注释中使用apiDoc提供的注解信息来生成文档信息。

在我们日常开发中一定会写开发文档，以前常见的做法是维护一个或多个markdown文件，每次api改动时都要去对应文件位置进行修改。这种方式维护起来相当麻烦，而且相对于网页来说markdown只能提供简单的阅览功能不能实时查看接口调用结果，对开发者来说api也不友好。所以找一个更好的文档处理方式已经是迫在眉睫，现在apiDoc可以让你可以解脱了。
apiDoc的gitHub地址：https://github.com/apidoc/apidoc。
apiDoc的文档地址：http://apidocjs.com/

二.Ubuntu安装apiDoc

按照官方文档安装apiDoc会出现一些问题。主要原因是因为apiDoc需要依赖nodejs，所以需要先安装nodejs然后安装apiDoc就可以了。

2.1 安装nodejs

更新ubuntu软件源

sudo apt-get update
sudo apt-get install -y python-software-properties software-properties-common
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update

安装nodejs

sudo apt-get install nodejs
sudo apt install nodejs-legacy
sudo apt install npm

更新npm的包镜像源

sudo npm config set registry https://registry.npm.taobao.org
sudo npm config list

全局安装n管理器(用于管理nodejs版本)

sudo npm install n -g

安装最新的nodejs（stable版本）

sudo n stable
sudo node -v

2.2安装apiDoc

上面的操作顺利完成后再执行下面命令就OK了。

sudo npm install apidoc -g

三.apiDoc入门

3.1 运行官方Demo

首先下载官方github上的源代码。
然后进入

apidoc/example/

最后执行

apidoc -i example/ -o doc/

这个命令就能满足基本需求了，详细的命令参数查看官方文档。生成的文档在指定的文件doc中，打开index.html。官方在线例子
apiDoc文档网页

3.2 配置文件介绍

如Demo中的文件结构
.
├── _apidoc.js 需要生成api文档的源代码文件
├── apidoc.json 配置文件
├── example.js 需要生成api文档的源代码文件
├── footer.md 生成api文档的自定义头部信息，支持markdown标签。
└── header.md 生成api文档的自定义底部信息，支持markdown标签。

apidoc.json文件相当简单对比Demo生成的文档可以轻松理解。

{"name": "apidoc-example-test","version": "0.3.0","description": "apidoc example project","title": "Custom apiDoc browser title","url" : "https://api.github.com/v1","sampleUrl": "https://api.github.com/v1","header": {"title": "My own header title","filename": "header.md"},"footer": {"title": "My own footer title","filename": "footer.md"},"template": {"withCompare": true,"withGenerator": true}
}

3.3 常用注解介绍

具体文档可参考：http://apidocjs.com/

/*** @api {get} /user/:id Read data of a User* @apiVersion 0.3.0* @apiName GetUser* @apiGroup User* @apiPermission admin** @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.** @apiParam {Number} id The Users-ID.** @apiExample Example usage:* curl -i http://localhost/user/4711** @apiSuccess {Number}   id            The Users-ID.* @apiSuccess {Date}     registered    Registration Date.* @apiSuccess {Date}     name          Fullname of the User.* @apiSuccess {String[]} nicknames     List of Users nicknames (Array of Strings).* @apiSuccess {Object}   profile       Profile data (example for an Object)* @apiSuccess {Number}   profile.age   Users age.* @apiSuccess {String}   profile.image Avatar-Image.* @apiSuccess {Object[]} options       List of Users options (Array of Objects).* @apiSuccess {String}   options.name  Option Name.* @apiSuccess {String}   options.value Option Value.** @apiError NoAccessRight Only authenticated Admins can access the data.* @apiError UserNotFound   The <code>id</code> of the User was not found.** @apiErrorExample Response (example):*     HTTP/1.1 401 Not Authenticated*     {*       "error": "NoAccessRight"*     }*/
function getUser() { return; }

重点介绍下@apiParam：
语法：

@apiParam [(group)] [{type}] [field=defaultValue] [description]

描述如何将参数传递给你的api方法。文档描述
例如: @apiParam (MyGroup) {Number} id Users unique ID.
注意：该标签适用于三种参数形式
a.动态路由：http://localhost/sutdent/:id
b.请求参数：http://localhost/sutdent?id=:id
c.表单参数：http://localhost/sutdent
在生成文档中id参数可以在“Send a Sample Request”发送时被替换成具体的值方便查看api的返回结果。