APIDOC的使用
工具名称：APIDOC
Git地址：https://github.com/apidoc/apidoc
项目地址：http://apidocjs.com/
样例项目：http://apidocjs.com/example_basic/
APIDOC使用指南：https://www.jianshu.com/p/34eac66b47e3
全局安装
安装NodeJS后自动安装了npm管理工具，使用npm管理工具在cmd下安装apidoc
注意：Windows用户需在cmd下执行安装命令，不要在git bash下执行安装命令；如果安装过程中失败或安装到某一模块时停顿，则选择连接另外一个网络重试
cd d:cd nodejsnpm install apidoc -g
编写注释
编写header.md
### 错误代码
1. 返回成功的标识为 code，值为“200000”说明返回成功，值大于200000说明返回错误2. 返回的错误描述为 msg，值可能为空3. 返回的数据为 data，值可能为空
**示例代码**
成功
{ "code":200000, "msg":"操作成功", "data":"" }
失败
{ "code":200001, "msg":"参数不全", "data":"" }
编写错误码：例如：restapi/controllers/ResponseCode.php
<?php
/**
*
* User: qiaoweinqing
* Date: 2018/5/30
* Time: 19:51
*/
namespace restapi\controllers;
class ResponseCode
{
/**
* @apiDefine ResponseCode 返回码
*/
/**
* @apiDescription
* 200000 执行成功
*
* 200010 缺少参数
*
* 200020 系统错误
*
* 201001 - 204000 标签模块
* @api {常量} 类ResponseCode
* @apiParam {200000} SUCESS_CODE 返回成功
* @apiParam {200010} ERROR_CODE_MISS_PARAM 缺少参数
*
* @apiParam {201001} ERROR_CODE_TAG_NAME_IS_NULL 标签名称不能为空
* @apiParam {201002} ERROR_CODE_PARENT_TAG_CODE_IS_NULL 父级标签编码不能为空
* @apiParam {201003} ERROR_CODE_ATTRIBUTES_REQUIRED 参数必填
* @apiParam {201004} ERROR_CODE_TAG_SAVE_FAILED 创建或修改标签失败
* @apiParam {201005} ERROR_CODE_TAG_ID_IS_NULL 标签ID不能为空
* @apiParam {201006} ERROR_CODE_TAG_ID_NOT_EXISTENT 标签不存在
* @apiParam {201007} ERROR_CODE_TAG_DELETE_FAILED 删除标签失败
* @apiParam {201008} ERROR_CODE_PERMISSION_DENY 无权限
*
* @apiGroup ResponseCode
*/
public function responserCode(){
}
const SUCESS_CODE=200000;
const ERROR_CODE_MISS_PARAM=200010;
// 标签
const ERROR_CODE_TAG_NAME_IS_NULL = 201001;
const ERROR_CODE_PARENT_TAG_CODE_IS_NULL = 201002;
const ERROR_CODE_ATTRIBUTES_REQUIRED = 201003;
const ERROR_CODE_TAG_SAVE_FAILED = 201004;
const ERROR_CODE_TAG_ID_IS_NULL = 201005;
const ERROR_CODE_TAG_ID_NOT_EXISTENT = 201006;
const ERROR_CODE_TAG_DELETE_FAILED = 201007;
const ERROR_CODE_PERMISSION_DENY = 201008;
}
编写API：例如：restapi/controllers/TagController.php
<?php
/**
* 道强
*/
namespace restapi\controllers;
use core\models\Tag;
use Yii;
use restapi\controllers\CommonController;
use restapi\controllers\ResponseCode;
use service\tag\TagService;
class TagController extends CommonController
{
public $enableCsrfValidation = false;
/**
* @apiDefine TagController 标签管理
* 标签编码规则：使用创建当天的6位年月日加上当天的标签生成6位顺序数；例如：2019年04月19日生成的第二个标签，编码为"190419000002"
*/
/**
* @api {post} /tag/create-or-update-children 创建或更新子标签
* @apiName actionCreateOrUpdateChildren
* @apiGroup TagController
* @apiDescription 在指定标签下创建或更新多个字标签的信息，主要包括更新字标签的名称和标签的类型
*
* @apiParam {String} platform 平台唯一标识
* @apiParam {String} [user] 用户唯一标识
* @apiParam {String} parent_tag_code 父级标签编码
* @apiParam {Array} children 字标签信息列表
* @apiParam {String} children.tag_name 子标签名称
* @apiParam {String} children.tag_code 子标签编码
* @apiParam {Number} children.tag_type 子标签类型
* @apiParamExample {json} 请求示例
* {
* "platform": "yaogonghui",
* "user": "",
* "parent_tag_code": "190419000001",
* "children": [
* {
* "tag_name": "规格",
* "tag_code": "190419000002",
* "tag_type": 1,
* },
* {
* "tag_name": "产地",
* "tag_code": "190419000003",
* "tag_type": 1,
* }],
* }
* @apiSuccess {Number} success_num 创建或更新子标签成功条数
* @apiSuccess {Array} children 子标签信息列表
* @apiSuccess {Number} children.id 子标签ID
* @apiSuccess {String} children.platform 子标签所属平台
* @apiSuccess {String} children.user 子标签所属用户
* @apiSuccess {String} children.tag_name 子标签名称
* @apiSuccess {String} children.tag_code 子标签编码
* @apiSuccess {Number} children.tag_type 子标签类型
* @apiSuccess {String} children.tag_icon 子标签图标
* @apiSuccess {Number} children.tag_sequence 子标签显示顺序
* @apiSuccess {String} children.tag_remark 子标签备注说明
* @apiSuccess {Number} children.created_at 子标签创建时间戳
* @apiSuccess {Number} children.updated_at 子标签更新时间戳
* @apiSuccess {Number} children.is_del 子标签是否软删除
*
* @apiSuccessExample 返回示例
* {
* "code": 200000,
* "ret": {
* "success_num": 2,
* "children": [
* {
* "id": "2",
* "platform": "",
* "user": "",
* "tag_name": "规格",
* "tag_code": "190419000002",
* "tag_type": 1,
* "tag_icon": "",
* "tag_sequence": 1,
* "tag_remark": "",
* "created_at": 1555593200,
* "updated_at": 1555593200,
* "is_del": 0,
* },
* {
* "id": "3",
* "platform": "",
* "user": "",
* "tag_name": "产地",
* "tag_code": "190419000003",
* "tag_type": 1,
* "tag_icon": "",
* "tag_sequence": 2,
* "tag_remark": "",
* "created_at": 1555593200,
* "updated_at": 1555593200,
* "is_del": 0,
* }]
* },
* "alertMsg": "创建或更新子标签成功!"
* }
*
* @apiError 201004 创建或修改标签失败
* @apiError 200010 缺少参数
* @apiError 201001 标签名称不能为空
* @apiError 201002 父级标签编码不能为空
*/
public function actionCreateOrUpdateChildren()
{
$params = Yii::$app->request->post();
$result = TagService::createOrUpdateChildren($params);
return $this->responseData($result['data'], $result['code'], $result['msg']);
}
/**
* @api {post} /tag/update 修改标签
* @apiName actionUpdate
* @apiGroup TagController
* @apiDescription 修改标签的所属父级、名称
*
* @apiParam {String} platform 平台唯一标识
* @apiParam {String} [user] 用户唯一标识
* @apiParam {String} tag_code 标签编码
* @apiParam {String} parent_tag_code 父级标签编码
* @apiParam {String} tag_name 标签名称
* @apiParamExample {json} 请求示例
* {
* "platform": "yaogonghui",
* "user": "18519654001",
* "tag_code": "190419000002",
* "parent_tag_code": "190419000001",
* "tag_name": "规格",
* }
* @apiSuccess {Number} success_num 成功条数
* @apiSuccess {String} tag_code 标签编码
* @apiSuccess {String} parent_tag_code 父级标签编码
* @apiSuccess {String} tag_name 标签名称
* @apiSuccessExample 返回示例
* {
* "code": 200000,
* "ret": {
* "success_num": 1,
* "tag_code": "190419000002",
* "parent_tag_code": "190419000001",
* "tag_name": "规格",
* },
* "alertMsg": "修改标签信息成功!"
* }
* @apiError 201004 创建或修改标签失败
* @apiError 200010 缺少参数
* @apiError 201001 标签名称不能为空
* @apiError 201002 父级标签编码不能为空
*/
public function actionUpdate()
{
// var_dump(Yii::$app->request->get());
// var_dump(Yii::$app->request->post());
// var_dump(Yii::$app->request->bodyParam);
// var_dump(json_decode(Yii::$app->request->getRawBody(), true));
$params = Yii::$app->request->post();
$result = TagService::update($params);
return $this->responseData($result['data'], $result['code'], $result['msg']);
}
/**
* @api {post} /tag/delete 删除标签及其所有子标签
* @apiName actionDelete
* @apiGroup TagController
*
* @apiParam {String} platform 平台唯一标识
* @apiParam {String} [user] 用户唯一标识
* @apiParam {String} tag_code 标签编码
* @apiParamExample {json} 请求示例
* {
* "platform": "yaogonghui",
* "user": "",
* "tag_code": "190419000001",
* }
* @apiSuccess {Number} success_num 成功条数
* @apiSuccessExample 返回示例
* {
* "code": 200000,
* "ret": {"success_num": 3},
* "alertMsg": "删除标签及其字标签成功!"
* }
*
* @apiError 201007 删除标签失败
*/
public function actionDelete()
{
$params = Yii::$app->request->post();
$result = TagService::delete($params);
return $this->responseData($result['data'], $result['code'], $result['msg']);
}
/**
* @api {post} /tag/update-sequence 标签移位
* @apiName actionUpdateSequence
* @apiGroup TagController
* @apiDescription 将标签移动至参照物标签的后面
*
* @apiParam {String} platform 平台唯一标识
* @apiParam {String} [user] 用户唯一标识
* @apiParam {String} tag_code 标签编码
* @apiParam {String} dest_tag_code 参照物标签的编码
* @apiParamExample {json} 请求示例
* {
* "platform": "yaogonghui",
* "user": "",
* "tag_code": "190419000002",
* "dest_tag_code": "190419000003",
* }
* @apiSuccess {Number} success_num 影响的标签记录数
* @apiSuccessExample 返回示例
* {
* "code": 200000,
* "ret": {"success_num": 5},
* "alertMsg": "标签移位成功!"
* }
*
* @apiError 201004 创建或修改标签失败
*/
public function actionUpdateSequence()
{
$params = Yii::$app->request->post();
$result = TagService::updateSequence($params);
return $this->responseData($result['data'], $result['code'], $result['msg']);
}
/**
* @api {get} /tag/list-tree 标签树列表
* @apiName actionListTree
* @apiGroup TagController
*
* @apiParam {String} platform 平台唯一标识
* @apiParam {String} [user] 用户唯一标识
* @apiParam {String} [tag_code_path] 标签编码从父级至子级使用文件目录分隔符"/"拼接
* @apiParam {String} [deep=0] 从叶子标签开始计算的深度，0代表无限级深度
* @apiParamExample {json} 请求示例
* {
* "platform": "yaogonghui",
* "user": "18519654001",
* "tag_code_path": "190419000001/190419000002",
* "deep": 1
* }
*
* @apiSuccess {Array} list 标签列表
* @apiSuccess {Number} list.id 标签ID
* @apiSuccess {String} list.platform 标签所属平台
* @apiSuccess {String} list.user 标签所属用户
* @apiSuccess {String} list.tag_name 标签名称
* @apiSuccess {String} list.tag_code 标签编码
* @apiSuccess {Number} list.tag_type 标签类型
* @apiSuccess {String} list.tag_icon 标签图标
* @apiSuccess {Number} list.tag_sequence 标签显示顺序
* @apiSuccess {String} list.tag_remark 标签备注说明
* @apiSuccess {Number} list.created_at 标签创建时间戳
* @apiSuccess {Number} list.updated_at 标签更新时间戳
* @apiSuccess {Number} list.is_del 标签是否软删除
* @apiSuccess {Array} list.children 字标签列表
* @apiSuccess {Array} pagination 分页信息
* @apiSuccess {Number} pagination.total 总条数
* @apiSuccess {Number} pagination.pageSize 每页条数
* @apiSuccess {Number} pagination.current 当前页
* @apiSuccessExample 返回示例
*
* {
* "code": 200000,
* "ret": {
* "id": "1",
* "platform": "",
* "user": "",
* "tag_name": "白芍",
* "tag_code": "190419000001",
* "tag_type": 1,
* "tag_icon": "",
* "tag_sequence": 1,
* "tag_remark": "",
* "created_at": 1555593200,
* "updated_at": 1555593200,
* "is_del": 0,
* "children": [
* {
* "id": "2",
* "platform": "",
* "user": "",
* "tag_name": "规格",
* "tag_code": "190419000002",
* "tag_type": 1,
* "tag_icon": "",
* "tag_sequence": 1,
* "tag_remark": "",
* "created_at": 1555593200,
* "updated_at": 1555593200,
* "is_del": 0,
* "children": [
* {
* "id": "4",
* "platform": "",
* "user": "",
* "tag_name": "统货",
* "tag_code": "190419000004",
* "tag_type": 1,
* "tag_icon": "",
* "tag_sequence": 1,
* "tag_remark": "",
* "created_at": 1555593200,
* "updated_at": 1555593200,
* "is_del": 0,
* }]
* }]
* "pagination": {
* "total": 3,
* "pageSize": 20,
* "current": 1
* }
* },
* "alertMsg": "标签列表查询成功"
* }
* @apiError 201006 标签不存在
*/
public function actionListTree()
{
$params = Yii::$app->request->post();
// $params['tag_code_path'] = '190419000001';
// $params['deep'] = 2;
if (!isset($params['user'])){
$params['user'] = '';
}
if (!isset($params['tag_code_path'])){
$params['tag_code_path'] = '';
}
if (!isset($params['deep'])){
$params['deep'] = 0;
}
$result = TagService::listTree($params);
// echo '<pre>';
// print_r($result);
// echo '</pre>';
// die;
return $this->responseData($result['data'], $result['code'], $result['msg']);
}
}
生成API文档
cd f: cd project/chgg-user-service-api cd restapi
apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc
解释：
# APIDOC的使用命令api/controllers指的是RestAPI代码目录api/web指的是RestAPI的入口脚本index.php的目录api/web/apidoc指的是API文档的存放目录
apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc
可封装未sh脚本
./genapidoc.sh #具体内容为
apidoc -i restapi/controllers/ -c restapi/web/ -o restapi/web/apidoc
实例文档地址：
http://tagdoc.test.chinahanguang.com/index.html
生成结果
更多示例
/**
* @apiDefine TestController 测试管理
*/
/**
*
* @apiDeprecated 现在请使用(#Test:_test)
* @api {post} /tag/test 01-测试
* @apiGroup TestController
* @apiName actionTest
* @apiVersion 1.6.2
* @apiPermission 无
* @apiExample {curl} 使用curl
* curl -i http://localhost/tag/test
*
* @apiHeader {String} access_token 授权令牌
* @apiHeaderExample {json} 请求头示例
* {
* "access_token": "abcdddd78789a7t89e8t9t9ew8t7e89t89te"
* }
* @apiParam {String} [firstname] Optional 姓
* @apiParam {String} lastname Mandatory 名
* @apiParam {String} country="中国" Mandatory 国籍
* @apiParam {Number} [age=18] Optional 年龄
* @apiParam (Login) {String} pass 登录密码
* @apiParamExample {json} 请求示例
* {
* "content": "This is an example content"
* }
* @apiSuccess {String} firstname 姓
* @apiSuccessExample 返回示例
* {
* "code": 200000,
* "ret": {
* "id": 1,
* "pid": "0",
* "tag_name": "药材"
* "tag_code": "0011"
* },
* "alertMsg": "创建标签成功!"
* }
* @apiSampleRequest http://www.example.com
* @apiError 10001 缺少参数
* @apiErrorExample {json} 错误示例
* HTTP/1.1 404 Not Found
* {
* "error": "未找到用户"
* }
*/
public function actionTest()
{
}
APIDOC的使用的更多相关文章
- apidoc
1.安装node http://nodejs.cn/download/ 下载二进制包,解压,配置环境 export NODE_HOME=/usr/local/nodeexport PATH=$NODE ...
- 基于php开发的RESTful ApiDoc文档
apiDoc基于rest的web API文档生成器,可以根据代码注释生成web api文档,自动生成静态的html网页文档,不仅支持项目版本号,还支持API版本号. 使用apiDoc不需要自己麻烦的调 ...
- ApiDoc 文档使用方式
1.安装node.js 2.打开node.js 命令窗(shell)键入npm install apidoc -g 自动安装(几分钟) 3. C:\Users\user\AppData\Roaming ...
- apidoc，一个相当不错的文档生成器
http://apidocjs.com/ 例子:myapp目录下的MyCode.java /** * * @api {get} /company/list 获取公司信息 * @apiName 获取公司 ...
- webApi文档好帮手-apidoc使用教程
来源:http://blog.csdn.net/xumin198908/article/details/41964159 在开发后台接口的过程中,我们肯定要提供一份api接口文档给终端app. 目前大 ...
- 使用apidoc根据JS文件生成接口文档
1.安装nodejs.下载网址:http://www.nodejs.org: 2.安装apidoc.运行cmd,切换到nodejs的安装目录,在命令行输入: 1 npm install apidoc ...
- 关于apidoc文档生成不了的一个原因
前几天在写完API后,写注释文档,然后很习惯的去用apidoc取生成注释文档,但是奇怪的事发生了,没有注释的内容,也没有报错:注释代码如下: /* * @api {get} /applet/:id 根 ...
- apidoc快速生成在线文档，apidoc生成静态文件的生成规则以及原理分析
在老大的指引下,需要将系统的json文件格式转换成apidoc的json格式,也就是json格式的重组,但是这个apidoc的生成格式是不固定的,因为apidoc有自己一套的生成规则,我需要研究一下是 ...
- Node与apidoc的邂逅——NodeJS Restful 的API文档生成
作为后台根据需求文档开发完成接口后,交付给前台(angular vue等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找.前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用, ...
- 接口文档神器之apidoc
//@desn:apidoc linux环境 windows环境使用 //@desn:码字不宜,转载请注明出处 //@author:张慧源 <turing_zhy@163.com> / ...
随机推荐
- 待解决问题 ：JDBC indexInsert.addBatch(); 为什么不生效 PSTM
JDBC indexInsert.addBatch(); 为什么不生效 PSTM
- P1577 切绳子（二分）
思路:先来分析一下数据范围,是1e4个数据,但是,是double类型,结果不超过0.01那么在绳子最大的情况下,单纯的找正确答案暴力的话就是1e7的时间复杂度,再乘上1e4的数据,这样肯定不行.那么很 ...
- spring boot启动报错
Exception encountered during context initialization - cancelling refresh attempt: org.springframewor ...
- AI Haar特征
Haar特征,也叫矩形特征,有四种特征(模板):边缘特征.线性特征.中心特征.对角线特征.每种模板都包含黑白两种区域. 模板的特征值=白色区域的像素和-黑色区域的像素和,反映的是图像的灰度变化情况. ...
- face detection[HR]
该模型hybrid-resolution model (HR),来自<finding tiny faces>,时间线为2016年12月 0 引言 虽然大家在目标识别上有了较好的进步,可是检 ...
- Spring MVC数据绑定入门总结
1.基本类型 基本类型参数不可为空 正例:http://localhost:8080/demo/he?id=2 反例:http://localhost:8080/demo/he?id=(报400错误) ...
- 使用hibernate造成的MySql 8小时问题解决方案
本文借鉴了网上的很多博客,在此不再声明 总结 1.增加 MySQL 的 wait_timeout 属性的值(不推荐) mysql5之前的版本,可以在jdbc连接的url中加入:autoReconnec ...
- 使用docker Registry快速搭建私有镜像仓库
当我们执行docker pull xxx的时候,docker默认是从registry.docker.com这个地址上去查找我们所需要的镜像文件,然后执行下载操作.这类的镜像仓库就是docker默认的公 ...
- 一篇 JPA 总结
概述 下面是 JDBC 在 Java 应用和数据库之间的位置,充当着一个中间者,供 Java 应用程序访问所有类别的数据库,建立一个标准 JPA 如同 JDBC 一样,为 Java 应用程序使用 OR ...
- H5 详情和概要标签
38-详情和概要标签 概要信息 详情信息 --> 郑伊健 简介:郑伊健,1967年10月4日出生于中国香港,籍贯广东恩平,香港影视演员.流行男歌手.1988年参加新秀歌唱大赛加入无线电视,因拍摄 ...