apidoc自动生成接口文档

写文档是开发者经常要做的事情,今天介绍一个自动生成文档的工具apidoc。使用起来非常简单,一键快速生成文档,操作非常方便。

安装:

 npm install apidoc -g


在需要写文档的目录编写配置文件apidoc.json:

{
  "name": "接口文档名称",
  "version": "1.0.0",
  "description": "接口文档描述",
  "title": "接口文档浏览器标题",
  "url" : "http://api.abc.com/",
  "header": {
    "title": "接口通用规则",
    "filename": "../header.md"
  },
  "footer": {
    "title": "API 错误返回值说明",
    "filename": "../footer.md"
  }
}

上面的例子引入了公共的头部和底部,支持md模式:

footer.md:

# API 错误返回值说明

## 错误返回示例
   {
     "code" : -1,
     "msg" : "params missing",
   }

## HTTP 状态码
code | 描述 | 说明
--- | --- | ---
-1 | 错误提交 | 具体看返回的错误信息
401 | 鉴权失败 | access_token过期或者不正确,重新登录
404 | 路由不存在或者资源不存在 | 访问的url不存在或者对应资源不存在
500 | 服务器内部错误 | 内部服务器出错

header.md:

## API 调用规则

本文档中所有请求服务端 API 接口的请求均使用此规则校验,以下不再重复说明。

API 接口统一请求URL ```http://api.abc.com/```

每次请求 API 接口时,均需要提供 HTTP Request Header,具体如下:

名称 | 类型 | 说明
--- | --- | ---
```nonce``` | String | 随机生成的```32```位数字
```timestamp``` | String | 客户端时间,时间戳
```auth``` | String | ```(选填)```不需用户登录的 API 不传该项,如需用户登录的 API ,需要传该项
```sign``` | String | 数据签名。

header和footer是选填的,可以没有!


使用(将api目录下面的接口在html目录生成文档):

apicod -i api/ -o html/

如果api目录下面没有接口文件则会返回错误信息

{"Path":"D:\\xds\\xxxxx\\test","level":"error","message":"No files found."}


写入一个测试接口goods.php:

/**
* @apiVersion 1.0.0
* @api {post}  goods.php  获取商品
* @apiName goods_list
* @apiGroup Goods
* @apiParam {String} r goods.goods_list
* @apiParam {Number} [page] 页码 默认为1
* @apiParam {String} [keywords] 搜索关键词 默认为空
* @apiParam {String} [order] 按什么排序  sales 按销量 minprice 按价格 createtime 按时间 空为默认按时间倒序排序
* @apiParam {String} [by] 搜索排序 desc 倒序 asc为顺序 默认desc
*
* @apiSuccess {Number} code 返回信息码 200 表示请求成功
* @apiSuccess {String} msg 返回说明信息
* @apiSuccess {String} data 返回的数据
*
* @apiSuccessExample Success-Response:
*          {"code":0,"msg":"ok","data":{"goods_list":[{"gid":"123","title":"测试商品","thumb":"http://abc/test.jpg","fake_price":"650.00","price":"205.00","min_price":"45.00","max_price":"75.00","is_discount":"0","sales":"10","total":"99","desc":"商品描述"}],"total":"30","page_size":10}}
*
*/

/**
* @apiVersion 1.0.0
* @api {post}  goods.php  收藏商品
* @apiName collect_goods
* @apiGroup Goods
* @apiParam {String} r goods.collect_goods
* @apiParam {Number} gid 商品编号
*
* @apiSuccess {Number} code 返回信息码 200 表示请求成功
* @apiSuccess {String} msg 返回说明信息
*
* @apiSuccessExample Success-Response:
*          {"code":0,"msg":"ok"}
*
*/

目录结构:

QQ截图20200517082850.png

(demo在附件)



重新运行生成命令:

apidoc -i api/ -o html/

然后在html里面可以直接访问index.html查看文档了

QQ截图20200517082557.png

QQ截图20200517083428.png


注意:每次更新了接口文件都需要重新执行生成apidoc命令生成。


apidoc-demo.zip



其他详细教程看官方文档:https://apidocjs.com/


评论/留言