• 安装apidoc
  • 配置(apidoc.json)
    • apidoc.json配置项
  • apidoc注释参数
    • @api
    • @apiErrorExample
    • @apiDefine
    • @apiDeprecated
    • @apiDescription
    • @apiError
    • @apiExample
    • @apiGroup
    • @apiParam
    • @apiHeader
    • @apiHeaderExample
    • @apiIgnore
    • @apiName
    • @apiParamExample
    • @apiPermission
    • @apiPrivate
    • @apiSampleRequest
    • @apiSuccess
    • @apiSuccessExample
    • @apiUse
    • @apiVersion
  • 生成接口文档

安装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 示例详情(兼容多行)

例：

/***@api {get} /user/getUserById/:id 获取用户数据 - 根据id* @apiErrorExample {json} Error-Response:*     HTTP/1.1 404 Not Found*     {*       "error": "UserNotFound"*     }*/

@apiDefine

定义注释模块(类似于代码中定义一个常量)，对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次，便可以在其他注释模块中随便引用，最后在文档导出时会自动替换所引用的注释模块，定义之后您可以通过@apiUse来引入所定义的注释模块。(注:可以同时使用@apiVersion来定义注释模块的版本)

@apiDefine name [title] [description]

参数列表:

参数 必填 描述
name yes 注释模块名称(唯一)，不同@apiVersion可以定义相同名称的注释模块
title no 注释模块标题
description no 注释模块详细描述(详细描述另起一行，可包含多行)

例：

/*** @apiDefine        FailResponse* @apiErrorExample  Response (fail):*     {*       "code":"error"*       "error_message": "错误内容"*     }*//*** @apiDefine        SuccessResponse* @apiSuccessExample  Response (success):*     {*       "code":"0"*       "error_message": ""*       "data":"内容"*     }*//*** @apiUse             SuccessResponse** @apiUse             FailResponse*/

@apiDeprecated

标注一个接口已经被弃用

@apiDeprecated [text]

参数列表:

参数 必填 描述
text yes 多行文字描述

例：

/*** @apiDeprecated use now (#Group:Name).** Example: to set a link to the GetDetails method of your group User* write (#User:GetDetails)*/

@apiDescription

api接口的详细描述

@apiDescription [text]

参数列表:

参数 必填 描述
text yes 多行文字描述

例：

/*** @apiDescription This is the Description.* It is multiline capable.** Last line of Description.*/

@apiError

错误返回参数

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

参数列表:

参数 必填 描述
(group) no 所有的参数都会通过这个参数进行分组，如果未设置，默认值为Error 4xx
{type} no 返回类型，例如{Boolean}， {Number}， {String}， {Object}，{String[]}（字符串数组），…
field yes 返回id
description no 参数描述

例：

/*** @api {get} /user/getUserById/:id 获取用户数据 - 根据id* @apiError UserNotFound The <code>id</code> of the User was not found.*//*** @apiError (错误分组) {Object} xxx xxxxxxxx*/

@apiExample

接口方式请求示例

@apiExample [{type}] titleexample

参数列表:

参数 必填 描述
type no 请求内容格式
title yes 示例标题
example yes 示例详情(兼容多行)

例：

/*** @api {get} /user/getUserById/:id* @apiExample {curl} Example usage:*     curl -i http://127.0.0.1/user/getUserById/1*/

@apiGroup

定义接口所属的接口组，虽然接口定义里不需要这个参数，但是您应该在每个接口注释里都添加这个参数，因为导出的接口文档会以接口组的形式导航展示。

@apiGroup name

参数列表:

参数 必填 描述
name yes 接口组名称(用于导航,不支持中文)

例：

/*** @apiDefine User 用户信息*/
/*** @api {get} /user/getUserById/:id* @apiGroup User*/

@apiParam

接口请求体参数

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

参数列表:

参数 必填 描述
(group) no 所有的参数都会以该参数值进行分组(默认Parameter)
{type} no 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
{type{size}} no 返回类型,同时定义参数的范围{string{…5}}意为字符串长度不超过5{string{2…5}}意为字符串长度介于25之间
{number{100-999}}意为数值介于100999之间
{type=allowedValues} no 参数可选值{string=“small”}意为字符串仅允许值为"small"{string=“small”,“huge”}意为字符串允许值为"small"、“huge”{number=1,2,3,99}意为数值允许值为1、2、3、99{string {…5}=“small”,"huge"意为字符串最大长度为5并且值允许为:“small”、“huge”
field yes 参数名称(定义该请求体参数为必填)
[field] yes 参数名称(定义该请求体参数为可选)
=defaultValue no 参数默认值
description no 参数描述

例：

/*** @api {get} /user/getUserById/:id* @apiParam {Number} id Users unique ID.*//*** @api {post} /user/* @apiParam {String} [firstname]  Optional Firstname of the User.* @apiParam {String} lastname     Mandatory Lastname.* @apiParam {String} country="DE" Mandatory with default value "DE".* @apiParam {Number} [age=18]     Optional Age with default 18.** @apiParam (Login) {String} pass Only logged in users can post this.*                                 In generated documentation a separate*                                 "Login" Block will be generated.*/

@apiHeader

描述接口请求头部需要的参数(功能类似@apiParam)

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

参数列表:

参数 必填 描述
(group) no 所有的参数都会以该参数值进行分组(默认Parameter)
{type} no 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field yes 参数名称(定义该头部参数为必填)
[field] yes 参数名称(定义该头部参数为可选)
=defaultValue no 参数默认值
description no 参数描述

例：

/*** @api {get} /user/getUserById/:id* @apiHeader {String} access-key Users unique access-key.*/

@apiHeaderExample

请求头部参数示例

@apiHeaderExample [{type}] [title]example

参数列表:

参数 必填 描述
type no 请求内容格式
title no 请求示例标题
example yes 请求示例详情(兼容多行)

例：

/*** @api {get} /user/getUserById/:id* @apiHeaderExample {json} Header-Example:*     {*       "Accept-Encoding": "Accept-Encoding: gzip, deflate"*     }*/

@apiIgnore

如果你需要使用该参数，请把它放到注释块的最前面。如果设置了该参数，那么该注释模块将不会被解析(当有些接口还未完成或未投入使用时，可以使用该字段)

@apiIgnore [hint]

参数列表:

参数 必填 描述
hint no 描接口忽略原因描述

例：

/*** @apiIgnore Not finished Method* @api {get} /user/getUserById/:id*/

@apiName

接口名称，每一个接口注释里都应该添加该字段，在导出的接口文档里会已该字段值作为导航子标题，如果两个接口的@apiVersion和@apiName一样，那么有一个接口的注释将会被覆盖(接口文档里不会展示)

@apiName name

参数列表:

参数 必填 描述
name yes 接口名称(相同接口版本下所有接口名称应该是唯一的)

例：

/*** @api {get} /user/getUserById/:id* @apiName getUserById*/

@apiParamExample

请求体参数示例

@apiParamExample [{type}] [title]example

参数列表:

参数 必填 描述
type no 请求内容格式
title no 请求示例标题
example yes 请求示例详情(兼容多行)

例：

/*** @api {get} /user/getUserById/:id* @apiParamExample {json} Request-Example:*     {*       "id": 1*     }*/

@apiPermission

允许访问该接口的角色名称

@apiPermission name

参数列表:

参数 必填 描述
name yes 允许访问的角色名称(唯一)

例：

/*** @api {get} /user/getUserById/:id* @apiPermission none*/

@apiPrivate

定义私有接口，对于定义为私有的接口，可以在生成接口文档的时候，通过在命令行中设置参数 --private false|true来决定导出的文档中是否包含私有接口

@apiPrivate

例：

/*** @api {get} /user/getUserById/:id* @apiPrivate*/

@apiSampleRequest

设置了该参数后，导出的html接口文档中会包含模拟接口请求的form表单；如果在配置文件apidoc.json中设置了参数sampleUrl,那么导出的文档中每一个接口都会包含模拟接口请求的form表单，如果既设置了sampleUrl参数，同时也不希望当前这个接口不包含模拟接口请求的form表单，可以使用@apiSampleRequest off来关闭。

@apiSampleRequest url

参数列表:

参数 必填 描述
url yes 模拟接口请求的url@apiSampleRequest http://www.example.com意为覆盖apidoc.json中的sampleUrl参数@apiSampleRequest off意为关闭接口测试功能

例：
发送测试请求到:http://api.github.com/user/getUserById/:id

/*** @api {get} /user/getUserById/:id*/

发送测试请求到:http://test.github.com/some_path/user/getUserById/:id(覆盖apidoc.json中的sampleUrl参数)

/*** @api {get} /user/getUserById/:id* @apiSampleRequest http://test.github.com/some_path/*/

关闭接口测试功能

/*** @api {get} /user/getUserById/:id* @apiSampleRequest off*/

发送测试请求到http://api.github.com/some_path/user/getUserById/:id(由于没有设置apidoc.json中的sampleUrl参数，所以只有当前接口有模拟测试功能)

/*** @api {get} /user/getUserById/:id* @apiSampleRequest http://api.github.com/some_path/*/

@apiSuccess

接口成功返回参数

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

参数列表:

参数 必填 描述
(group) no 所有的参数都会以该参数值进行分组,默认值:Success 200
{type} no 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field yes 返回值(返回成功码)
=defaultValue no 参数默认值
description no 参数描述

例：

/*** @api {get} /user/getUserById/:id* @apiSuccess {String} firstname Firstname of the User.* @apiSuccess {String} lastname  Lastname of the User.*/

包含(group):

/*** @api {get} /user/getUserById/:id* @apiSuccess (200) {String} firstname Firstname of the User.* @apiSuccess (200) {String} lastname  Lastname of the User.*/

返回参数中有对象:

/*** @api {get} /user/getUserById/:id* @apiSuccess {Boolean} active        Specify if the account is active.* @apiSuccess {Object}  profile       User profile information.* @apiSuccess {Number}  profile.age   Users age.* @apiSuccess {String}  profile.image Avatar-Image.*/

返回参数中有数组：

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

@apiSuccessExample

返回成功示例

@apiSuccessExample [{type}] [title]example

参数列表:

参数 必填 描述
type no 返回内容格式
title no 返回示例标题
example yes 返回示例详情(兼容多行)

例：

/*** @api {get} /user/getUserById/:id* @apiSuccessExample {json} Success-Response:*     HTTP/1.1 200 OK*     {*       "code":"0"*       "message": ""*       "data":"加密内容"*     }*/

@apiUse

引入注释模块，如果当前模块定义了@apiVersion,那么版本相同或版本最近的注释模块会被引入

@apiUse name

参数列表:

参数 必填 描述
name yes 引入注释模块的名称

例：

/*** @apiDefine MySuccess* @apiSuccess {string} firstname The users firstname.* @apiSuccess {number} age The users age.*//*** @api {get} /user/getUserById/:id* @apiUse MySuccess*/

@apiVersion

定义接口/注释模块版本

@apiVersion version

参数列表:

参数 必填 描述
version yes 版本号(支持APR版本规则:major.minor.patch)

例：

/*** @api {get} /user/getUserById/:id* @apiVersion 1.6.2*/

小诀窍，笔者把接口中的通用部分利用apiDefine摘出来，放在一个公共文件中，之后可以利用apiUse去调用，或许部分注释参数可以直接使用apiDefine即可调用。

生成接口文档

当然你注释参数写好了之后它也不会帮你自动生成，你需要自己运行以下命令：
例：

apidoc -f ".*\\.php$"  -i ./application -o ./public/apidoc

参数列表:

参数 描述
-h, --help 查看帮助文档
-f --file-filters 指定读取文件的文件名过滤正则表达式(可指定多个)例如: apidoc -f “.*\.js&quot;−f&quot;.∗.ts
"−f".∗.ts” 意为只读取后缀名为js和ts的文件默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters 指定不读取的文件名过滤正则表达式(可指定多个)例如:apidoc -e “.*\.js$” 意为不读取后缀名为js的文件默认:’’
-i, --input 指定读取源文件的目录例如：apidoc -i myapp/ 意为读取myapp/目录下面的源文件默认值:./
-o, --output 指定输出文档的目录例如：apidoc -o doc/ 意为输出文档到doc目录下默认值:./doc/
-t, --template 指定输出的模板文件例如:apidoc -t mytemplate/默认:path.join(__dirname, ‘…/template/’)(使用默认模板)
-c, --config 指定包含配置文件(apidoc.json)的目录例如:apidoc -c config/默认:./
-p, --private 输出的文档中是否包含私有api例如:apidoc -p true 默认:false
-v, --verbose 是否输出详细的debug信息例如:apidoc -v true默认:false

之后你就能通过浏览器进行访问了，比如http://localhost/apidoc

apiDoc之api接口文档生成相关推荐

  1. 扔掉Swagger，试试这款功能强大，零注解侵入的API接口文档生成工具！

    欢迎关注方志朋的博客,回复"666"获面试宝典 介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart-d ...

  2. 一款零注解API接口文档生成工具

    smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,基于接口源码来分析生成接口文档,不采用任何注解侵入到业务代码中.只需要按照java-do ...

  3. PHP API 接口文档生成 简单版本 基于一位大哥的代码改的

    https://github.com/cnPauLi/apidoc.git 使用方法如下 /** * 获取所有列表 * api GET api.php/index/index/all * @param ...

  4. Swagger自动接口文档生成框架————springboot整合swagger总结

    swagger简介: swagger是一款开源的api接口文档生成工具. Swagger的项目主页:https://swagger.io/    目前比较流行的做法是在代码中加入swagger相关的注 ...

  5. apidoc 自动化生成 api接口文档

    手写api接口太麻烦. 学习了apidoc自动生成接口文档,这边做一下整理 要用组件那就必须先安装 apidoc,做一下全局安装 npm install apidoc -g 新建配置文件apidoc. ...

  6. Api 接口文档是什么？如何直接使用 ApiDoc 生成接口文档

    api接口文档 现代化开发大部分都是一种前后端分离的开发模式,前端与后端分别独立进行开发.等后续再去统一的联调.前后端分离的开发模式下,前后端沟通的成本增加,如何减少口头的交流成了关键.这时有一份高端 ...

  7. Laravel使用Apidoc注解自动生成Api接口文档

    本教程从零开始搭建laravel项目,并安装Apidoc扩展及使用注解生成Api接口文档的教程,该扩展支持 多应用/版本.Markdown文档.在线接口调试.接口生成器.代码模板生成器.Mock调试数 ...

  8. python生成接口文档_使用apiDoc实现python接口文档编写

    使用apiDoc实现python接口文档编写 apiDoc的安装 npm install apidoc -g 生成api的终端命令:apidoc -i 代码所在路径-o 生成文件的路径 接口文档的编写 ...

  9. 开发日记-20190328 关键词 利用eolinker一键快速生成API接口文档

    今天感觉效率真的很低= =各个层面的,apk发布到现场发现出现了问题,所以一个下午都在忙着解决现场出现的问题,领导一直打电话询问进度,午觉也没有睡所以今天预计的很多计划都处于停滞状态,像昨天规划的今天 ...

  10. 整合swagger2生成Restful Api接口文档

    整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...

最新文章

  1. OpenGL Transformation
  2. mysql format函数对数字类型转化的坑
  3. Python Web实时消息后台服务器推送技术---GoEasy
  4. 工程设计+算法规模化真的是AI突破吗？DeepMind唇读系统ICLR遭拒
  5. SaltStack 安装及配置认证
  6. 效率提升一倍，成本下降 80%，阿里云落地全球最大规模云原生实践
  7. 【资源】首发：徐亦达老师的机器学习课件及下载（中文目录）
  8. 网易笔试题：最大的奇约数
  9. 海南大学计算机科学与技术专业考研,2021年海南大学计算机科学与技术(081200)硕士研究生招生信息_考研招生计划和招生人数 - 学途吧...
  10. arcgis server 9.3 查看地图服务时出现No Content错误
  11. （二）ubuntu使用launchpad.net线上编译
  12. 2014 Unity 璀璨星空夜
  13. 莱布尼兹其实离开我们并不遥远
  14. 岁月温柔-20 妈妈在省医院第一天
  15. vant-Weapp实现省市区三级联动顶部弹出列表
  16. 如何判断电脑是否被黑客入侵
  17. 跟刀客一起追寻昨日的足迹
  18. ACM比赛常用技巧算法
  19. 用这个公式编辑器可以打出标准的绝对值公式
  20. 【微信多开】windows系统同时登陆多个微信

热门文章

  1. App测试的11点建议
  2. 从sql2016导出数据库到sql2014
  3. Origin 软件去除demo 水印
  4. 机器学习的1000+篇文章总结
  5. 2022数学建模美赛
  6. 美赛论文Latex模板说明
  7. mciSendCommand对本地音乐的播放
  8. ASP.NET MVC 3 Beta初体验之WebGrid
  9. IT项目建议书及可行性研究报告撰写格式
  10. DVWA全级别通关教程