API注释及参数


通过为API接口添加注释, 能大大加快API开发速度

注释使用方法

通过为方法添加注释, 简化API开发流程

namespace app\api\controllers;

use Cross\Core\Delegate;

/**
 * @Auth: wonli <wonli@live.com>
 * Class Main
 * @package app\api\controllers
 *
 * @cp_doc_info array('title' => 'CrossPHP API', 'version' => '0.0.1')
 * @cp_doc_global_params array('platform' => '来源平台', 'channel' => '渠道', 'version' => '客户端版本号')
 * @cp_api_spec 默认
 */
class Main extends Api
{
    /**
     * 默认控制器
     *
     * @cp_api get, /main/index, 获取框架当前版本号
     * @cp_request t|当前时间|1
     */
    function index()
    {
        $data['version'] = Delegate::getVersion();
        $data['t'] = $this->getInputData('t');

        $this->data['data'] = $data;
        $this->display($this->data);
    }
}

注释的类型

注释根据功能不同, 可以划分为纯文档型注释和文档加功能相结合的多功能注释

一, 类注释(纯文档型注释)

类注释一般是纯文档型注释. 主要用于生成API调试文档

  • 类顶部的全局注释(配置一次即可)

    @cp_doc_info array('title' => 'CrossPHP API', 'version' => '0.0.1')
      
    

    控制生成文档的标题和版本号

    @cp_doc_global_params array('platform' => '来源平台', 'channel' => '渠道', 'version' => '客户端版本号')
    
    

    每个请求都需要的公共参数配置

  • 每个类顶部均需配置的菜单型注释

    @cp_api_spec 默认
      
    

    接口类菜单名称, 在每个类顶部(@cp_api_ignore 指定的类除外)配置, 指定类的菜单名称

    @cp_api_ignore
    
    

    生成文档时忽略该类(一般为基类, 被文档生成程序略过)

二, 方法注释(文档和功能想结合的多功能注释)

这类注释需要写在每个方法的注释中, 用于生成表单及参数验证

  • @cp_api

    @cp_api get, /main/index, 获取框架当前版本号
    

    一共由三部分组成并以,分隔. 以上例为准:

    • get
      指定该接口允许的请求类型为GET, 其他类型访问该接口会返回错误提示

    • /main/index
      接口的访问地址

    • 获取框架当前版本号
      方法菜单名称(调试API文档)

  • @cp_request

    @cp_request t|当前时间|1
    
    

    用于指定接口所需参数, 每一个参数分为3个部分, 以|分隔, 多个参数以,分隔, 以上例为准:

    • t
      表示所需参数名称, 除了指定参数名称以外, 还可以通过加入:符号来设定表单类型. 比如:

      t:textarea 生成一个textarea
      t:select:1-安卓 2-iOS 生成一个select, option值和名称之间用-分隔, 多个option用空格分隔
      t:file|文件上传|0 文件上传输入框

    • 当前时间
      调试表单中的参数名称

    • 1
      是否强制要求该参数

获取参数

在控制器内部获取参数

$this->getInputData('t');
 

使用getInputData()方法获取参数, 在getInputData()方法内部首先会根据注释判断是不是必传参数, 然后调用filterData()方法对参数进行统一的过滤处理

文档生成

请查看cli下调试文档生成相关文档