apiDoc 详解 api接口文档生成

安装apidoc

官网

通过npm安装，请提前安装好npm

可以通过以下命令安装apidoc:

npm install apidoc -g

配置(apidoc.json)

每次导出接口文档都必须要让apidoc读取到apidoc.json文件(如果未添加配置文件，导出报错)，你可以在你项目的根目录下添加apidoc.json文件，这个文件主要包含一些项目的描述信息，比如标题、简短的描述、版本等，你也可以加入一些可选的配置项，比如页眉、页脚、模板等。
apidoc.json

{
   
  "name": "系统接口文档",
  "version": "0.0.1",
  "description": "文档总描述",
  "title": "apidoc浏览器自定义标题",
  "url" : "文档url地址"
}

如果你的项目中使用了package.json文件(例如:node.js工程)，那么你可以将apidoc.json文件中的所有配置信息放到package.json文件中的apidoc参数中：
package.json

{
   
 "name": "系统接口文档",
  "version": "0.0.1",
  "description": "文档总描述",
  "apidoc": {
   
    "title": "apidoc浏览器自定义标题",
 	 "url" : "文档url地址"
  }
}

apidoc.json配置项

参数	描述
name	工程名称如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取
version	版本如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取
description	工程描述如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取
title	浏览器标题
url	api路径前缀例如:https://api.github.com/v1
sampleUrl	如果设置了该参数，那么在文档中便可以看到用于测试接口的一个表单(详情可以查看参数@apiSampleReques)
header.title	页眉导航标题
header.filename	页眉文件名(markdown)
footer.title	页脚导航标题
footer.filename	页脚文件名(markdown)
order	接口名称或接口组名称的排序列表如果未定义，那么所有名称会自动排序"order": [ "Error", "Define", "PostTitleAndError", PostError"]

更多详情

apidoc注释参数

@api

【必填字段】否则，apidoc会忽略该条注释

@api {method} path [title]

参数列表:

参数	必填	描述
method	yes	请求类型:DELETE, GET, POST, PUT, ...更多
path	yes	请求路径
title	no	接口标题

例：

/**
* @api {get} /user/getUserById/:id 获取用户数据 - 根据id
*/

@apiErrorExample

接口错误返回示例(格式化输出)

@apiErrorExample [{type}] [title]
                 example

参数列表:

</

参数	必填	描述
type	no	响应类型
title	no	示例标题
example	yes	示例详情(兼容多行)