Controller - API注释标准

一、code样例

<?php
namespace App\Module\Sup\Controller\Api\V1\Order;
use Swork\Bean\BeanCollector;
use .....
/**
 * @Controller("/sup/api/v1/order")
 */
class OrderController extends BeanCollector
{
    /**
     * @Inject()
     * @var OrderLogic
     */
    private $orderLogic;
    /**
     * 获取用户订单列表
     * @param Argument $argument
     * @return array
     * @throws
     */
    public function pager(Argument $argument)
    {
        //外部参数
        $uid = Context::get('userId');
        /**
         * 订单状态
         * @var int
         * @sample 11
         */
        $odrstat = $argument->get('odrstat', 0);
        /**
         * 页码
         * @var int
         * @sample 1
         */
        $idx = $argument->get('idx', 1);
        /**
         * 每页行数
         * @var int
         * @sample 10
         */
        $size = $argument->get('size', 10);
        //查询字符
        $query = [
            'uid' => $uid,
            'odrstat' => $odrstat,
        ];
        //获取数据
        $list = $this->orderLogic->getPager($query, $idx, $size);
        //API返回
        /**
         * {
         *      list: [
         *          {
         *              okey: "101201904101123",  //订单号
         *              gid: "101201904101123",   //商品ID
         *              odrstat: 11,              //订单状态  11:待揽件  .....
         *              odrtime11: "2019-09-17 21:00",  //下单时间
         *              pname: "iPhone 8 全网通4G双卡双待 256G 深空灰色 美版" //商品信息
         *              refprice3: "6,553"         //预计帮卖价
         *              minprice: "2,199"          //保底售价
         *              prepayamt: "2,000"         //预付款
         *              payamt: "20",              //尾款
         *              saleprice: "1,000"         //销售价格
         *              totalamt："2，020",         //已收总金额
         *          }
         *      ]
         *      pager: {
         *          idx: 1,  页码
         *          size: 20, 当页行数
         *      },
         * }
         */
        return [
            'list' => $list,
            'pager' => [
                'idx' => $idx,
                'size' => count($list),
            ]
        ];
    }
}

二、解析说明

1）基本规范与其它的一致；此项特别要求两个地方：
a）外部参数注释：每个外部参数单独注释，把 参数名称、参数类型、样例数据 描述清楚；
b）返回样例子注释（固定：//API返回 ）；

参数注释：

<?php
        /**
         * 订单状态          ---- 第一行：参数名称
         * @var int        ---- 第二行：参数类型
         * @sample 11      ---- 第三行：样例数据
         */
        $odrstat = $argument->get('odrstat', 0);

返回注释：

<?php 
        //API返回
        /**
         * {
         *      list: [
         *          {
         *              okey: "101201904101123",  //订单号
         *              gid: "101201904101123",   //商品ID
         *              odrstat: 11,              //订单状态  11:待揽件  .....
         *              odrtime11: "2019-09-17 21:00",  //下单时间
         *              pname: "iPhone 8 全网通4G双卡双待 256G 深空灰色 美版" //商品信息
         *              refprice3: "6,553"         //预计帮卖价
         *              minprice: "2,199"          //保底售价
         *              prepayamt: "2,000"         //预付款
         *              payamt: "20",              //尾款
         *              saleprice: "1,000"         //销售价格
         *              totalamt："2，020",         //已收总金额
         *          }
         *      ]
         *      pager: {
         *          idx: 1,  页码
         *          size: 20, 当页行数
         *      },
         * }
         */
        return [
            'list' => $list,
            'pager' => [
                'idx' => $idx,
                'size' => count($list),
            ]
        ];

操作方法：在开发完成时，运行后，把结果复制至这里。

三、如此目的

相对普通Controller开发的，API开发的注释会麻烦一些。
为了给前端一目了解的API接口文档，系统自动通过扫描此类注释，生成API文档。

生成的例子：

四、无数据返回样例

<?php
    /**
     * 删除订单
     * @param Argument $argument
     * @return array
     * @throws
     */
    public function delete(Argument $argument)
    {
        /**
         * 订单ID
         * @var string
         * @sample 1
         */
        $oid = $argument->post('oid', '');
        //删除数据
        $this->orderLogic->delete($oid);
        //API返回
        /**
         * success
         */
        return 'success';
    }

注：API返回内容，仅有一个 sucess ，没有其它内容

五、错误返回样例#1

禁止在Logic层返回 sucess ，然后在Controller返回。

<?php
    /**
     * 删除订单
     * @param Argument $argument
     * @return array
     * @throws
     */
    public function delete(Argument $argument)
    {
        /**
         * 订单ID
         * @var string
         * @sample 1
         */
        $oid = $argument->post('oid', '');
        //删除数据
        $info = $this->orderLogic->delete($oid);  //logic层返回 success
        /*----------------------------
        /*  这个是错误的代码 ！！！！！
        /*----------------------------
        //API返回
        /**
         * success
         */
        return $info;
    }