控制器

控制器都放在 Http 目录，与 路由 相对应，控制器也按照终端进行了分组：

• Admin

• Api

• Frontapi

• Shopapi

• Super

• Thirdparty

每个分组下的目录结构如下：

• Api

  • V1

    • Action 控制器实际所在目录

    • Swagger Swagger定义目录

定义控制器

下面是一个基础控制器类的例子。需要注意的是，该控制器继承了 Laravel 的基类控制器。该基类控制器提供了一些便利的方法，比如 middleware 方法，该方法可以为控制器行为添加中间件：

namespace AftersalesBundle\Http\Api\V1\Action;

use EspierBundle\Jobs\ExportFileJob;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller as Controller;

use AftersalesBundle\Services\AftersalesService;

use Dingo\Api\Exception\ResourceException;

use EspierBundle\Traits\GetExportServiceTraits;

class Aftersales extends Controller
{
    use GetExportServiceTraits;

    public function getAftersalesDetail($aftersales_bn)
    {
        $companyId = app('auth')->user()->get('company_id');
        $aftersalesService = new AftersalesService();
        $result = $aftersalesService->getAftersalesInfo($companyId, $aftersales_bn);

        return $this->response->array($result);
    }
}

定义 API 文档

在 EcshopX 中每一个控制器方法都是一个 api都是一个接口，接口的出参和入参都是通过 注释来定义的，采用Swagger格式来定义。

控制器分组下的每一个版本都是一组 API ，定义一组 api 需要两步，以 AftersalesBundle 举例如下：

1、在 Swagger 目录下定义分组信息

定义 API 基本信息

//AftersalesBundle/Http/Api/V1/Swagger/Info.php
<?php
/**
 * @SWG\Swagger(
 *     schemes={"http"},
 *     host="localhost",
 *     basePath="/api",
 *     @SWG\Info(
 *         version="1.0",
 *         title="售后单商家端调用接口",
 *         description="售后单",
 *     ),
 *     produces={"application/json"},
 * )
 */

定义 API Tag

//AftersalesBundle/Http/Api/V1/Swagger/Tags.php
<?php
/**
 * @SWG\Tag(
 *   name="aftersales",
 *   description="售后单",
 * )
 */

根据需求定义接口所需数据对象：

//AftersalesBundle/Http/Api/V1/Swagger/AftersalesErrorRespones.php

<?php
namespace AftersalesBundle\Http\Api\V1\Swagger;

/**
 * @SWG\Definition(type="object")
 */
class AftersalesErrorRespones
{
    /**
     * @SWG\Property
     * @var string
     */
    public $message;

    /**
     * @SWG\Property
     * @var string
     */
    public $errors;

    /**
     * @SWG\Property(format="int32")
     * @var int
     */
    public $code;

    /**
     * @SWG\Property(format="int32")
     * @var int
     */
    public $status_code;

    /**
     * @SWG\Property
     * @var string
     */
    public $debug;
}

2、在 Action 目录中的控制器的方法定义接口

/**
     * @SWG\Get(
     *     path="/aftersales/{$aftersales_bn}",
     *     summary="获取售后单详情",
     *     tags={"aftersales"},
     *     description="获取售后单详情",
     *     operationId="getAftersalesDetail",
     *     @SWG\Parameter(
     *         name="Authorization",
     *         in="header",
     *         description="JWT验证token",
     *         required=true,
     *         type="string",
     *     ),
     *     @SWG\Parameter(
     *         name="aftersales_bn",
     *         in="path",
     *         description="售后单号",
     *         required=true,
     *         type="integer",
     *     ),
     *     @SWG\Response(
     *         response=200,
     *         description="成功返回结构",
     *     ),
     *     @SWG\Response( response="default", description="错误返回结构", @SWG\Schema( type="array", @SWG\Items(ref="#/definitions/AftersalesErrorRespones") ) )
     * )
     */
    public function getAftersalesDetail($aftersales_bn)
    {
        $companyId = app('auth')->user()->get('company_id');
        $aftersalesService = new AftersalesService();
        $result = $aftersalesService->getAftersalesInfo($companyId, $aftersales_bn);

        return $this->response->array($result);
    }

Swagger 定义参数详见 OpenAPI Specification

接口文档生成和接口测试

在通过 Swagger 注释的方式定义好接口文档后，可以通过本地开发环境查看和测试接口。

一、将 Swagger UI的资源拷贝到public目录中

执行以下命令：

php artisan api:swagger --setup

二、生成指定目录的Swagger API Josn

以 AftersalesBundle 举例如下：

php artisan api:swagger --output=src/AftersalesBundle/Http/Api/V1

执行完命令后，默认会在 storage/app/apidocs 目录下生成类似 售后单商家端调用接口[1.0].json文件。

可通过在 .env 中新增配置改变存储目录名称

SWAGGER_STORAGE_DIR=apidocs

三、启动服务查看和测试接口

可以通过 PHP 内置 server 快速启动

php -S 0.0.0.0:8005 -t public/

访问地址为：http://127.0.0.1:8085/api-doc 本机开发时，还需要将测试接口的地址修改为本地环境：

SWAGGER_API_HOST=127.0.0.1:8080
SWAGGER_API_BASE_PATH=/api

使用技巧： 在开发过程中可以，每次修改接口文档都需要重新生成接口文档，可以这样使用命令：

php artisan api:swagger --output=src/AftersalesBundle/Http/Api/V1 && php -S 0.0.0.0:8005 -t public/