Apidoc的安装和使用简介

1、apidoc是什么？

apidoc是一个可以将源代码中的注释直接生成api接口文档的工具，它支持各种不同的注释风格，可以在各种语言中使用。

具体见官网介绍：apidoc官网

2、apidoc的安装

第一步：由于apidoc依赖node.js的包管理工具npm进行安装，所以安装apidoc之前要先安装node.js。node.js下载

第二步：在命令行输入：

npm install -g apidoc
           

再输入：

apidoc -h
           

出现相关帮助信息，说明安装成功可以使用了

apidoc的使用

在指定文件的目录下打开命令行

，执行apidoc，便可以就可以自动生成一个doc文档。

index.html

就是生成的api接口文件。

注意：

1、在生成文件之前，要在该目录下添加一个apidoc.json文件，格式如下：

{
    "name":"接口文档名称",
    "version":"版本号",
    "title":"这里是页面导航标题",
    "url":"接口链接"
}
 

           

2、如果要在接口文件中添加头文件，则apidoc.json格式如下：

{
   "name":"接口文档名称",
    "version":"版本号",
    "title":"这里是页面导航标题",
    "url":"接口链接"，
    "header": {
        "title": "接口说明",
        "filename": "header.md"
    }
}
           

header.md

文件同样放在指定文件目录下

3、常用代码（具体细节见官网）

1、 @api {method} path [title]

Name	Description
method	请求的方法，例如：post、get、put……
path	请求路径
title	标题，通常用于导航和文章开头

2、@apiName name

Name	Description
name	唯一的方法名，主要作用： 当某接口有不同的版本时使用，可以被区分

3、@apiGroup name

Name	Description
name	分组名，用于导航栏中

4、@apiDescription text

Name	Description
text	描述

5、@apiVersion version

Name	Description
version	版本号(major.minor.patch)

6、@apiParam [(group)] [{type}] [description]

Name	Description
(group)	一个分组名，把所有的参数分成一组
{type}	参数的数据类型
description	描述

7、@apiSuccess [(group)] [{type}] field [description]

Name	Description
(group)	一个分组名，把所有的参数分成一组
{type}	参数的数据类型
description	描述