author: hjb2722404 head: https://avatars1.githubusercontent.com/u/10215241?v=3&s=460 date: 2017-03-15 title: thinkphp5的API文档生成库api_doc使用总结 tags: : API 自动化 category: 技术-后端 status: public summary: 本文记录了使用TP5的文档自动生成库api_doc的一点心得体会。
api_doc简介
api_doc是github上开源的一个TP5的API文档自动生成库,基于PHP语言编写,相比于其他API文档生成工具或库,它有以下优点:
- 不依赖其他库和环境
- 安装配置简单快捷
- 生成的文档界面直观,层级清晰
安装
### 通过命令行工具下载
$ git clone https://github.com/NTASTE/php_api_doc.git
通过github项目主页下载
打开该项目的github主页
点击ZIP下载按钮,下载后解压。
将文件夹改名为api_doc
并将整个文件夹移动到TP5项目的根目录,如图所示:
配置
进入api_doc/config
目录,编辑config.php
文件:
PS: 注意API控制器目录是相对于config.php的路径,如上例所对应的目录结构:
使用
### API输出数据说明
api_doc
对于API输出数据的说明采用了注释法,直接将注释写在API方法之前就行,一般都会有一个@desc
和若干个@return
字段,@return
字段的格式为:@return 返回字段类型 返回字段名称 返回字段说明
,返回字段类型有以下几种:
'string' => '字符串',
'int' => '整型',
'float' => '浮点型',
'boolean' => '布尔型',
'date' => '日期',
'array' => '数组',
'fixed' => '固定值',
'enum' => '枚举类型',
'object' => '对象',
示例文件
/application/v1/controller/Order.php
:
<?php
class Order {
/**
* 测试接口
* @desc 用于获取多个用户基本信息
* @return int code 操作码,0表示成功
* @return array list 用户列表
* @return int list[].id 用户ID
* @return string list[].name 用户名字
* @return string list[].note 用户来源
* @return string msg 提示信息
*/
public function test(){
return [];
}
/**
* 测试接口1
* @desc 用于获取多个用户基本信息
* @return int code 操作码,0表示成功
* @return array list 用户列表
* @return int list[].id 用户ID
* @return string list[].name 用户名字
* @return string list[].note 用户来源
* @return string msg 提示信息
*/
public function demo(){
return [];
}
public function getRules(){
return [
'demo' => [
'tel' => [
'name' => 'tel',
'type' => 'int',
'min' => 11,
'require' => true,
'desc' => '电话号码'
],
'password' => [
'name' => 'password',
'type' => 'int',
'min' => 6,
'require' => true,
'desc' => '登录密码'
]
],
'test' => [
'userIds' => [
'name' => 'user_ids',
'type' => 'array',
'format' => 'explode',
'require' => true,
'default' => '10',
'range' => [10,100],
'desc' => '用户ID,多个以逗号分割'
],
],
];
}
}
API输入参数说明
对于API的输入参数说明,api_doc
采用了统一在API类下面设置rules
来实现,如以上文件末尾所示例的,该方法统一为getRules()
方法,该方法返回一个多维数组,数组的第一维是API的方法名,第二维是输入参数标识,第三维是该参数的对该参数的属性要求,一般来说有以下几个:
'name' => 'user_ids', // 参数名称,API从请求中取参数以此名称为准
'type' => 'array', //参数类型
'format' => 'explode', //参数格式
'require' => true, //是否必须
'default' => '10', //默认值
'range' => [10,100], //取值范围
'desc' => '用户ID,多个以逗号分割' //对参数的说明和描述