Apidoc主要是用于生成API文档的工具，可以用于多种语言，包括java、javascript、php等

这里主要是为了写前端的APIDOC，方便交互是双方的使用;

工具的安装

工具包的安装

npm i apidoc [-g|-D]

可以-g全局安装，或者-D局部安装,因为只有开发环境需要apidoc包，因此项目依赖只需要放置在devDependencies中即可

VSCODE编辑器的支持，可以在扩展中搜索ApiDoc,最上面的ApiDoc Snippets是最受欢迎的支持工具，可以点击安装

APIDOC的生成

apidoc的配置文件

关于Apidoc的配置有两种方式，一种是在项目根目录中添加apidoc.json，另一种是直接在package.json种添加apidoc的配置

添加 apidoc.json 方式

{"name": "example","version": "0.1.0","description": "apiDoc basic example","title": "Custom apiDoc browser title","url" : "https://api.github.com/v1"
}

在package.json中添加配置方式

{"name": "example","version": "0.1.0","description": "apiDoc basic example","apidoc": {"title": "Custom apiDoc browser title","url" : "apiDoc base interface url"}
}

注意：

使用第二种方式时，因为 package.json 本身包含name，version，description等属性，若是apidoc不设置该属性，将使用package.json设置的属性值

若是第一种方式，不包含这些属性，可能使用apidoc包的默认值

apidoc配置属性

属性	描述
name	一般是项目名称，显示在生成的apidoc首页.
version	项目的版本号 .
description	项目的描述信息.
title	是配置生成html的title标签
url	设置api接口的前缀，所有api接口路径前会自动添加该值
sampleUrl	是否展示发送示例请求的pannel。取值URL,示例的接口请求前缀为该值；取值true，接口请求前缀为url属性值；取值false或者属性不存在，则不展示请求示例的操作pannel.@apiSampleRequest可以用来覆盖该值，设置某个特别接口的特性.
header	apidoc导航的顶部目录，可用于配置展示的md文件
title	顶部导航目录的名称
filename	顶部导航对应的引入的.md文件路径
footer	apidoc导航的底部目录，可用于配置展示的md文件
title	底部导航目录的名称
filename	底部导航对应的引入的.md文件路径
order	可以用于定义 api-names / group-names 的导出目录顺序.若不设置该值顺序随机.“order”: [ “Error”, “Define”,“PostTitleAndError”, “PostError”]

完整配置

{"name": "ApiDoc 服务","title": "ApiDoc 服务","version": "0.1.0","description": "Mock服务API文档","url": "http://127.0.0.1","sampleUrl": true,"header": {"title": "ApiDOC介绍","filename": "apidoc.md"},"footer": {"title": "综合介绍","filename": "apidoc.md"},"order":[]
}

设置header/footer，示例如下：

发送示例请求的pannel，示例如下：

当输入参数后点击发送按钮后显示Response，示例如下:

Apidoc文档生成

全局安装的apidoc,可以在项目的根目录下打开cmd终端，并执行以下命令；

如果是项目安装的apidoc，可以将以下命令添加到package.json文件的scripts中，可以直接双击执行该命令，避免每次接口变化时都要重新输入该命令,生成接口文档

apidoc -i 编译文件夹 -o 输出文件夹

编译文件夹：就是需要输出接口文档的文件所在文件夹，apidoc文档会自动识别相关参数，并编译这些代码文件

输出文件夹:生成接口文档的存储文件夹

apidoc命令执行后，根据命令生成的静态html页面，可以在输出文件夹点击html页面查看生成的静态页面，页面即是接口的列表

Api支持的标签

属性	使用
@api {method} path title	用于定义接口
@apiVersion version	设置接口文档的版本
@apiGroup name	接口分组
@apiDefine	定义结构块
@apiUse	使用定义的定义的@apiDefine结构
@apiPermission name	定义权限的名称
@apiDescription text	api的详细描述，text可以多行
@apiName name	用于导航的html属性值，主要是用作锚点
@apiPrivate	标记接口私有，根据生成的命令是否存在–private决定是否生成该接口
@apiDeprecated [text]	标记api废弃
@apiIgnore [hint]	接口编译时忽略，apidoc中不显示该接口
@apiSampleRequest	单独设置指定接口的请求pannel的显示
@apiQuery name	定义查询参数
@apiBody	定义接口的请求体
@apiExample	api使用示例
@apiParam	用于定义传递给@api的参数
@apiParamExample	用于定义@api中多行格式，例如Json格式的参数
@apiError	用于定义错误码返回参数
@apiErrorExample	错误码返回参数多行格式，例如Json格式的参数
@apiHeader	传递给api header的参数描述
@apiHeaderExample	传递给api header的多行参数描述
@apiSuccess	定义成功返回参数
@apiSuccessExample	定义成功返回多行参数，例如Json格式的参数

以下是关于标签的详细使用说明

@api

定义接口

@api {method} path title

method:get、post、put等定义接口交互类型
path：定义接口路径，如果路径中存在参数，使用:attr表明是路径参数
title：接口名称或描述

示例

@api {post} /user/del 删除设置
@api {get} /user/:nav 导航设置

@apiDescription

api的详细描述，text可以多行

@apiDescription text

@apiGroup

用于对@api接口分组,不用于@apiDefine，最好使用英文，否则编译后分组会出现错误

@apiGroup name

@apiName

用于导航的html源代码节点属性data-name等，不能在UI页面上直观的看到展示,不用于@apiDefine；因为是添加到html的属性上，所以推荐英文,主要是用作锚点，用于href等属性

@apiName name

@apiDeprecated

标记api废弃

@apiDeprecated [text]

如果接口直接被废弃，则直接添加

@apiDeprecated [废弃描述]

如果当前接口被废弃，有了可替换的新的接口，可以在描述中添加新接口的锚点链接，方便用户查看

//定义的接口
@apiGroup groupName
@apiName apiName//废弃接口
@apiDeprecated [废弃描述] [#groupName:apiName]

点击锚点跳转到分组groupName下的，名字为apiName的接口，因为涉及锚点跳转因此推荐这两个属性都使用英文命名

@apiIgnore

@apiIgnore [hint]

接口编译时忽略，apidoc中根本不显示该接口，没有该接口的任何信息，而@apiDeprecated则是在接口名称下添加Deprecated红色标记

@apiPrivate

给接口设置私有标签，然后根据生成文档的命令决定是否生成带有私有标签的接口

@apiPrivate

生成显示私有标签的接口：

apidoc -i  ./bin -o ./apidoc --private

不生成显示私有标签的接口：

apidoc -i  ./bin -o ./apidoc

@apiVersion

设置接口文档的版本

@apiVersion version

@apiSampleRequest

用于单独设置某个接口是否显示请求示例pannel。

若sampleUrl已经设置，就近原则，覆盖全局设置的apidoc.json文档中的设置 sampleUrl；

@apiSampleRequest url

url ： http接口前缀，或者路径前缀，例如：http://apidoc.com, /prefix/path

关闭当前接口的请求示例pannel：

@apiSampleRequest off

@apiPermission

导出一个权限的名称，如果该名称被@apiDefine 添加了注释，则鼠标滑过会有说明

@apiPermission name

@apiDefine

可以单独定义一个通用的结构，方便被其它多个@api的定义引用

@apiDefine name [title][description]

name ：定义块的名称
title ：如果name值是 @apiPermission 或者 @apiParam的名称时，该值就是弹框的别名
description ：当title是@apiPermission的值时才显示

普通的使用

定义结构：

/*** @apiDefine ResSuccess* @apiSuccess {string} resCode response code.* @apiSuccess {string} resMes response Message.* @apiSuccess {json} [data] response data.*/

此时结构中，如果定义description，此内容不会被引入

使用结构：

/*** @api {post} /user/del 删除设置* @apiUse ResSuccess*/

作为 apiPermission 的说明

定义结构：

/*** @apiDefine permission Manager* Manager user access* @apiSuccess {string} resCode response code.*/

此时结构中，如果定义其它内容，例如@apiSuccess不会被引入@api,只是作为@apiPermission的一个注释

使用结构：

/*** @api {post} /user/del 删除设置* @apiPermission permission*/

当定义了一个符合apiPermission标准的结构时，并定义了@apiSuccess等内容时，如果使用@apiUse引入，则引入成功返回的参数pannel，如果使用@apiPermission引入，则引入定义的说明文字与别名

@apiUse

用于使用@apiDefine定义的结构

@apiUse name

name，@apiDefine结构名称

@apiQuery

定义传递给接口的参数,查询参数,给apidoc添加Query Parameter(s)的pannel

@apiQuery [{type}] [field=defaultValue] [description]

type ：定义参数类型，{string}，{boolean}等
- {type{size}}：
  
  {string{…5}} 限定string长度最多5个字符.
  
  {string{2…5}} 限定string长度2-5个字符
  
  {number{100-999}} 限定参数属于 100 到 999之间
- {type=allowedValues}
  
  {string=“small”} 只有一个可选值
  
  {string=“small”,“huge”} 有多个可选值
  
  {number=1,2,3,99} 有多个可选值
  
  {string {…5}=“small”,“huge”} type设置size 与 allowedValues混合写法
field ：属性名称
- [field] 当前参数可选，非必选参数
- field[nestedField] 内嵌属性
```
@apiParam {Object} [address] 可选address参数
@apiParam {String} [address[street]] 可选内嵌street参数
```
- =defaultValue 设置默认值
description ：参数描述信息

@apiBody

定义传递给接口的参数,给apidoc添加Request Body的pannel

@apiBody [{type}] [field=defaultValue] [description]

参数说明同 @apiQuery

@apiParam

该标签用于定义api参数,为apidoc添加参数pannel，并且推荐定义出现在@api path中的参数，否则会报警

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

group ：定义pannel的名字，默认Parameter
type ：定义参数类型，{string}，{boolean}等
- {type{size}}：
  
  {string{…5}} 限定string长度最多5个字符.
  
  {string{2…5}} 限定string长度2-5个字符
  
  {number{100-999}} 限定参数属于 100 到 999之间
- {type=allowedValues}
  
  {string=“small”} 只有一个可选值
  
  {string=“small”,“huge”} 有多个可选值
  
  {number=1,2,3,99} 有多个可选值
  
  {string {…5}=“small”,“huge”} type设置size 与 allowedValues混合写法
field ：属性名称
- [field] 当前参数可选，非必选参数
- field[nestedField] 内嵌属性
```
@apiParam {Object} [address] 可选address参数
@apiParam {String} [address[street]] 可选内嵌street参数
```
- =defaultValue 设置默认值
description ：参数描述信息

@apiParamExample

该标签用于定义api参数多行示例,为apidoc添加示例块

@apiParamExample [{type}] [title]example

注意，example 另起一行，就按照上述格式

type ：参数数据类型
title ：参数名称
example ：是一个块状示例描述，多行

@apiExample

api的使用示例,为apidoc添加示例块

@apiExample [{type}] titleexample

type ：代码语言
title ：示例的名称
example ：示例详情，多行

 @apiExample {curl} Example usage:curl -i http://localhost/user/4711

@apiError

用于定义返回参数错误码，为接口添加返回错误码pannel

@apiError [(group)] [{type}] field [description]

group ：定义参数错误码pannel名称
type ：定义参数类型，{string}，{boolean}等
field：定义返回码
description:描述

示例如下：

/**
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/

@apiErrorExample

用于定义返回参数错误码多行格式，例如Json格式的参数，为apidoc添加示例块

@apiErrorExample [{type}] [title] example

type ：定义错误响应参数类型，一般是{json}
title: 返回example的名称
example: 是一个块状示例描述，多行

/*** @apiErrorExample {json} Error-Response:*     HTTP/1.1 404 Not Found*     {*       "error": "UserNotFound"*     }*/

@apiHeader

描述传递给Api-Header的参数，为apidoc添加pannel

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

group ：定义参数分组名称，如果没有该值默认为Parameter
type ：定义参数类型，{string}，{boolean}等
field ：属性名称
- [field] 当前参数可选，非必选参数
- =defaultValue 设置默认值
description ：属性字段参数描述信息

标签示例：

@apiHeader (MyHeaderGroup) {String} authorization Authorization value

@apiHeaderExample

描述传递给Api-Header的多行示例，为apidoc添加示例块

@apiHeaderExample [{type}] [title]example

type ：请求格式
title ：示例example名称
example ：详情示例，多行示例

/*
*  @apiHeaderExample {json} Header-Example:
*   {
*     "Accept-Encoding": "AcceptEncoding: gzip, deflate"
*   }
*/

@apiSuccess

定义成功返回参数的Pannel，apidoc添加成功返回参数pannel

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

group ：定义成功返回pannel的名称，如果没设置，默认Success 200
type ：定义参数类型，{string}，{boolean}等
field ：定义返回属性，成功返回码
description ：属性字段参数描述信息

/*** @apiSuccess {Object[]} profiles List of user profiles.* @apiSuccess {Number} profiles.age Users age.* @apiSuccess {String} profiles.image Avatar-Image.*/

@apiSuccessExample

定义成功返回多行参数的示例，例如Json格式的参数，为apidoc添加示例块

@apiSuccessExample [{type}] [title]example

type ：定义成功返回示例类型
title ：示例example名称
example ：详情示例，多行示例，例如json

/*
*  @apiSuccessExample {json} Success-Response:
*     HTTP/1.1 200 OK
*     {
*       "firstname": "John",
*       "lastname": "Doe"
*     }
*/

[apidoc]Apidoc-文档生成工具相关推荐

apiDoc 一款很不错api文档生成工具
apiDoc 一款很不错api文档生成工具,在开发接口的时候,需要给同事看相应的接口文档.给大家推荐一个生成文档的工具--apiDoc,最后生成的文档以网页的形式发布,方便快捷,便于阅读. 创建项目目 ...
php自写api文档生成工具
框架改版后的第二个版本定下来了,这两天也比较轻松,于是就折腾给项目建个好看的api文档. 各种折腾.先是折腾phpDocumentor2,用phpdoc开源工具来建立文档,好不容易安装成功,各个模板都 ...
APIDOC- API文档生成工具——node
文章目录 APIDOC apidoc拥有以下特点 apidoc安装使用后端的代码需要给前端写一个接口文档. 可以自动生成. APIDOC apidoc是一个简单的RESTful API文档生成工具, ...
java smart算法_Java Restful API 文档生成工具 smart-doc
谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性. 如果代码有生命,为什么不换种方式和它对话! 一.背景没有背景.就自己做自己 ...
Apiggs —— 非侵入性的 RestDoc 文档生成工具
程序员一直以来都有一个烦恼,只想写代码,不想写文档.代码就表达了我的思想和灵魂. Python提出了一个方案,叫docstring,来试图解决这个问题.即编写代码,同时也能写出文档,保持代码和文档的一 ...
.NET平台开源项目速览(4).NET文档生成工具ADB及使用
.NET平台开源项目速览(4).NET文档生成工具ADB及使用原文:.NET平台开源项目速览(4).NET文档生成工具ADB及使用很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习 ...
Doxygen自动文档生成工具在Eclipse中的集成及使用举例
你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...
unity mysql生成cexcel_【C#附源码】数据库文档生成工具支持（Excel+Html）
[2015] 很多时候,我们在生成数据库文档时,使用某些工具,可效果总不理想,不是内容不详细,就是表现效果一般般.很多还是word.html的.看着真是别扭.本人习惯用Excel,所以闲暇时,就简单的 ...
java 接口文档工具_一款Java基于注释的接口文档生成工具
一. 痛点你还在手动维护接口文档嘛,花一个下午不停的复制粘贴代码里面的注释接口字段变动,还得去更新文档,更新不及时导致文档不同步或者你使用了swagger之类的基于注解,依靠运行时的文档工具,看 ...
数据库文档生成工具V1.0
这是一款基于C#开发语言编写的数据库文档生成工具,主要实现了 SQlServer+MYsql 数据库表结构说明文档的生成,并且支持 SQLServer 数据库的备份功能,主要可以把数据库的表以及表的详 ...

[apidoc]Apidoc-文档生成工具