Apidoc生成接口文档-PHP

一开始使用PHPDocumentor生成接口文档,但是,感觉有点不够方便,后换成了apidoc.

安装

npm install apidoc -g

或者使用yarn安装

yarn global add apidoc

配置(apidoc.json)

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

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

我的--order排序

{
  "name": "安全质量检查ServiceAPIs",
  "version": "1.0.0",
  "description": "安全质量检查接口文档",
  "title": "API接口文档",
  "url": "http://safety.local:8889",
  "sampleUrl": "http://safety.local:8889",
  "order": [
    "基础接口",
    "myWorkbench",
    "检查活动",
    "getActivity",
    "getActivityInfo",
    "addActivityFile",
    "getRectify",
    "getInfoList",
    "handleActivity",
    "searchAccount"
 ]
}

示例:

/**
 * @api {GET} /api.php?m=check&a=getActivity 查看所有检查活动列表
 * @apiName getActivity
 * @apiGroup 检查活动
 * @apiDescription 检查活动列表
 *
 * @apiParam {String} token="s2iph9ik" 用户token
 * @apiParam {Number} adminid=3 用户id
 * @apiParam {Number=0,1,2,3,4} [type=0] 活动性质 0默认 1专项检查 2综合检查 3月度检查 4季度检查
 * @apiParam {Number=0,1,2,3} [status=0] 检查活动状态 0未开始 1进行中 2已完成 3已取消
 * @apiParam {Number} [page=1] 页数
 * @apiParam {Number} [num=10] 每页展示数量
 *
 * @apiSuccess {Number} code 返回信息码 200 表示请求成功
 * @apiSuccess {String} msg 返回说明信息
 * @apiSuccess {boolen} success 请求成功
 * @apiSuccess {json} data 成功数据
 * @apiSuccess {Number} activity_record_num 问题记录数量
 *
 * @apiSuccessExample Success-Response:
 * HTTP/1.1 200 OK 
 *   
 * {       
 *     "code": 200, 
 *      "msg": "", 
 *      "data": [{
 *           "id": "6", 
 *           "title": "2020年第二季度综合检查",
 *           "property": "专项检查",
 *           "check_project": "",
 *           "dept": "xxxx部",
 *           "check_range": "xx标段,xx标段",
 *           "check_status": "0",
 *           "start_time": "2020-08-19",
 *           "end_time": "2020-08-31", 
 *           "add_time": "2020-09-01 09:00:49",
 *           "summary": "检查检查",
 *           "remark": "",
 *           "file": "17", 
 *           "check_name": "bim", 
 *           "check_id": "13", 
 *           "check_phone": "17611241011",
 *           "uid": "3",
 *           "issue_status": "已整改回复",
 *           "file_info": [{
 *               "filename": "创优网上填报系统.docx",
 *               "filepath": "upload/2020-05/22_12131327.docx"
 *           }], 
 *           "activity_record_num": 2
 *   }],
 *      "success": true
 *   } 
 * 
 * @apiSampleRequest /api.php?m=check&a=getActivity
 */

使用命令:

apidoc -i webmain/task/api/ -o ./apidoc/

可以写在PHP文件,然后执行PHP脚本:

<?php
//运行apidoc命令，更新apidoc文档
exec('apidoc -i webmain/task/api/ -o ./apidoc/');

效果:

其他的解释请查看这篇文章吧:
apiDoc详解