Linux系统安装、使用apidoc教程

apidoc安装教程：

1、首先要确定是否已经安装了node.js，如果未安装可以参考node.js的安装教程：https://blog.csdn.net/ba_qi/article/details/103177812

2、apidoc可以利用npm来快速安装，输入命令 npm install apidoc -g 进行apidoc的安装，如下图：

下图为安装完毕：

3、输入apidoc -v 命令，如果出现如下图所示的界面，则表示apidoc已安装成功

apidoc 使用： 

apidoc 一些重要的参数如下表所示：

参数	描述
-f	选择要解析的文件，支持正则表达式。-f参数可以使用多次，多个表达式可以对应不同的-f。如：apidoc -f ".*\.js$" -f ".*\\.ts$"
-i	选择源代码所在的位置。如：apidoc -i myapp/
-o	选择生成的目标文件所在的位置。如：apidoc -o apidoc/
-t	为生成文件选择模板，可以创建和使用自定义的模板。（笔者注：目前为止，笔者还没有使用过这个参数）
-h	跟绝大多数命令一样，这个参数可以打印出帮助文档

apidoc -i src/ -o apidoc/ # 可以通过搜索src目录中的文件快速的生成文档文件，并将这些文件放在apidoc目录下。

apidoc -h # 显示帮助信息

使用apidoc

一个典型的文件目录结果如下图所示。

 

其中：

apidoc.json：apidoc的项目级配置文件，它必须位于整个工程目录顶层。

Demo1.java：用于演示的demo源文件，它可以位于整个工程目录的顶层目录及其子目录下。apidoc会搜索整个工程目录选择所有可能的源文件。

apidoc.json和Demo1.java中包含的代码分别如下：

{
 "name": "demo",
 "version": "1.0.0",
 "description": "这是一个简单的apidoc的demo",
 "title": "demo",
 "url" : "https://api.github.com/v1"
}

/**
 * @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.
 */

Shell中输入apidoc -i ./ -o ../../public/doc命令，如果出现如下图所示的Done结果，则表明文档已经生成，位于同级目录的apidoc（与-o ../../public/doc对应）目录下 

 

打开../../public/doc目录，可以看到如下图所示的静态Web文件。

浏览器中访问index.html就可以看到生成在线接口文档网站

配置

apidoc.json文件是项目级的配置文件，接下来简单地介绍一下其中常用的配置项。

配置名	描述
name	工程名。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
version	工程文档的版本号。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
description	工程详细描述。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
title	文档标题，显示在文档界面的最上方
url	整个api url的前缀，接下来的所有接口url都会加上这个前缀
sampleUrl	api示例的url前缀。如果设置了这个值，则界面中显示请求表单，可以用于测试接口
header
title	文档头（header）的连接锚点名
filename	文档头所使用的文件
footer
title	文档尾（footer）的连接锚点名
filename	文档尾所使用的文件
order	接口的排列顺序list，如果不指定，则由apidoc自行确定

 

一个比较完整的配置文件如下：

{

 "name": "demo",

 "version": "1.0.0",

 "description": "这是一个简单的apidoc的demo",

 "title": "api接口demo",

 "url": "https://api.github.com/v1",

 "sampleUrl": "https://api.github.com/v1/test",

 "header": {

  "title": "接口文档",

  "filename": "header.md"

 },

 "footer": {

  "title": "footer",

  "filename": "footer.md"

 },

 "order": [

  "Error",

  "Define",

  "PostTitleAndError",

  "PostError"

 ]

}

更多的配置项请参考apidoc官方文档站点。