README

用于在 Sorokin.Media 中标准化 API 设置和工作的组件

组件包含一组预先准备好的类，用于简化并标准化编写 API 服务。

ActionModel - 用于描述模型中的操作的类（按钮、链接等）
ApiAnswer - 用于标准化服务器响应的类。描述了常见的错误，以简化代码编写
Controller - 描述控制器的工作，认证方法，排除的操作等。应从 ApiController 继承项目中所有 API 控制器
CrudModels - 描述类，允许快速并以统一标准描述 CRUD 服务（首先是模型列表）。
Interfaces - 可在项目工作中与 API 一起使用的接口。
Traits - 可在项目工作中使用 API 的特性。

组件安装

可以使用 composer 安装组件

"sorokinmedia/yii2-api-helpers": "dev-master"

组件配置

在 common/config/main.php 中添加组件的连接

'apiHelpers' => [
    'class' => \sorokinmedia\api_helpers\ApiHelpersComponent::class,
    'authenticator_class' => \yii\filters\auth\HttpBearerAuth::class,
    'authenticator_excerpt' => [
        'options',
        'login',
        'check-token',
        'password-reset-request',
        'password-reset',
        'confirm-email',
        'check-login',
        'check-email',
        'register',
    ]
],

authenticator_class - 用于认证的类

authenticator_excerpt - 不应用认证规则的动作数组

在 api/config/main.php 中配置组件 urlManager

'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => false,
    'showScriptName' => false,
    'rules' => \yii\helpers\ArrayHelper::merge(
        // классы имплементирующие RoutesInterface с описанием роутов
        \api\config\routes\RouteClass::getRoutes(),
        ...
    )
],

在 api/config/main.php 中配置组件 request

'request' => [
    'enableCookieValidation' => false,
    'enableCsrfValidation' => false,
    'parsers' => [
        'application/json' => \yii\web\JsonParser::class,
    ],
],

在 api/config/main.php 中配置组件 response

'response' => [
    'class' => 'yii\web\Response',
    'on beforeSend' => function ($event) {
        $response = $event->sender;
        if ($response->data !== null) {
            if(!empty($response->data['status']) && $response->data['status'] < 404) {
                if (isset($response->data['status']) && isset($response->data['name']) && isset($response->data['message'])) {
                    $response->data = [
                        'response' => null,
                        'messages' => [
                            new \sorokinmedia\api_helpers\ApiAnswer\RestMessage([
                                'type' => \sorokinmedia\api_helpers\ApiAnswer\RestMessage::TYPE_SERVER_ERROR,
                                'message' => $response->data['name'] . " : " . $response->data['message'],
                                'targetField' => null,
                            ]),
                        ],
                        'status' => (empty($response->data['status']) ? \sorokinmedia\api_helpers\Controller\ApiController::STATUS_ERROR : $response->data['status']),
                    ];
                }
            }
        }
    },
],

API 文件夹结构

api
    config                      конфигурация апи
        routes                  классы роутов, имплементирующие интерфейс RoutesInterface
    controllers                 контроллеры, определяющие уровень доступа
    modules                     модули апи (версионные модули v1, v2 и т .д.)
        v1                      модуль для первой версии API
            models              рестовые модели для описания структур данных
            modules             модули API, обычно разделенные по ролям пользователей
            
    runtime                     файлы сгенерированные в runtime
    tests                       тесты для API
    web                         содержит файл точки входа и вспомогательные ресурсы
        doc                     папка, со сгенерированной документацией apiDoc

组件使用

具有访问级别的控制器类

控制器允许一次性定义所有子控制器的访问级别。指定系统定义的角色列表。

示例：具有“仅限管理员角色用户”访问限制的控制器

<?php
namespace api\controllers;

use common\components\user\entities\User\User;
use sorokinmedia\api_helpers\Controller\ApiController;
use yii\filters\AccessControl;

/**
 * Class AdminApiController
 * @package api\controllers
 */
class AdminApiController extends ApiController
{
    use ApiDocTrait;

    /**
     * @return array
     * @throws \yii\base\InvalidConfigException
     */
    public function behaviors()
    {
        return array_merge(parent::behaviors(), [
            'access' => [
                'class' => AccessControl::class,
                'rules' => [
                    [
                        'allow' => true,
                        'roles' => [User::ROLE_ADMIN],
                    ],
                ],
            ],
        ]);
    }

}

路由定义类

示例：一个描述路由的类，它实现了 RoutesInterface 接口并实现了静态方法 getRoutes()，该方法返回路由数组。

<?php
namespace api\config\routes;

use sorokinmedia\api_helpers\Interfaces\RoutesInterface;

/**
 * Class ApiAdminRoutes
 * @package api\config\routes
 */
class ApiAdminRoutes implements RoutesInterface
{
    /**
     * @return array
     */
    public static function getRoutes() : array
    {
        return [
            //user list
            'GET /v1/admin/user/list' => '/v1/admin/user/list',
        ];
    }
}

数据结构描述文件

示例：描述用户模型的文件，它用于 REST 特性，关于此类特性的详细描述在 sorokinmedia/yii2-ar-relations 组件中。

需要重写 fields() 方法，该方法返回模型属性以所需的形式。

<?php
namespace api\modules\v1\models;

use api\modules\v1\models\traits\RestRelationClassTrait;
use common\components\user\entities\User\User;

/**
 * Class RestUser
 * @package api\modules\v1\models
 */
class RestUser extends User
{
    use RestRelationClassTrait;

    /**
     * @return array
     */
    public function fields()
    {
        return [
            'id',
            'created_at',
            'username' => function (self $user){
                return $user->username;
            },
            'status' => function (self $user){
                return [
                    'id' => $user->status_id,
                    'alias' => $user->status
                ];
            },
            'auth_key',
        ];
    }
}

模块 v1 内的控制器示例

示例：继承自具有访问级别的控制器的控制器文件。

在 use 部分也指定了所有用于描述服务器响应（ApiAnswer）和 CRUD 列表（CrudModels）的类。

控制器必须包含对 behaviors() 方法的重写，其中描述了哪些类型的请求对控制器中描述的操作可用。

<?php
namespace api\modules\v1\modules\admin\controllers;

use api\controllers\AdminApiController;
use sorokinmedia\api_helpers\CrudModels\{
    CrudColumn
    filters\CrudDatePickerFilter,
    filters\CrudInputNumberFilter,
    filters\CrudInputTextFilter,
    filters\CrudNoFilter,
    filters\CrudSelectFilter,
    orders\CrudOrderable,
    orders\CrudUnorderable
};
use sorokinmedia\api_helpers\ApiAnswer\{
    ApiAnswerError,
    ApiAnswerFormValidationError,
    ApiAnswerLog,
    ApiAnswerModelNotFound,
    ApiAnswerParamValidationError,
    ApiAnswerSuccess
};
use yii\filters\VerbFilter;

/**
 * Class UserController
 * @package api\modules\v1\modules\admin\controllers
 */
class UserController extends AdminApiController
{
    /**
     * @return array
     * @throws \yii\base\InvalidConfigException
     */
    public function behaviors()
    {
        return array_merge(parent::behaviors(), [
            'verbs' => [
                'class' => VerbFilter::class,
                'actions' => [
                    'list' => ['get'],
                    'view' => ['get'],
                    'filter-statuses' => ['get'],
                    'filter-roles' => ['get'],
                    'block' => ['post'],
                    'unblock' => ['post'],
                    'add-role' => ['post'],
                    'revoke-role' => ['post'],
                ],
            ],
        ]);
    }
    
    //описание экшенов внутри контроллера
    public function actionTest()
    {
        ...
    }

##如何编写 API 文档

使用 npm 包 apiDoc 描述 API http://apidocjs.com/

###描述示例

示例

@api - 请求类型，请求 URL，英文名称
@apiDescription - 简要描述服务，指明作者
@apiName - 简短服务名，将在文档菜单中显示
@apiGroup - 服务组，该服务将在文档菜单中添加到该组
@apiVersion - API 版本
@apiParam - 描述输入参数。参数类型，名称，简要描述
@apiSuccess - 描述成功执行服务时的响应结构
@apiUse SuccessRespond - 使用来自 ApiDocTrait.php 的标准成功响应模板
@apiUse ErrorRespond - 使用来自 ApiDocTrait.php 的标准错误响应模板

/**
 * @api {get} /v1/admin/user/list Get users list
 * @apiDescription Список пользователей (Руслан)
 * @apiName Get users list
 * @apiGroup Admin user list
 * @apiVersion 1.0.0
 *
 * @apiParam {String} [username] Запрос для поиска по нику
 * @apiParam {String} [email] Email
 * @apiParam {Integer} [id] ID пользователя
 * @apiParam {Integer} [limit=100] Сколько показывать
 * @apiParam {Integer} [page=1] Страница пагинации
 * @apiParam {String} [order_by="id"] По какому полю сортировать (id, created_at, username, status)
 * @apiParam {String} [order="SORT_DESC"] Направление сортировки (SORT_DESC, SORT_ASC)
 * @apiParam {Array} [status] Статусы
 * @apiParam {Array} [roles] Роли
 *
 * @apiSuccess {Object} response Список пользователей
 * @apiSuccess {Object[]} response.users Найденные пользователи
 * @apiSuccess {Integer} response.users.id ID пользователя
 * @apiSuccess {Integer} response.users.created_at Дата регистрации (unixstamp)
 * @apiSuccess {String} response.users.username Никнейм
 * @apiSuccess {String} response.users.fullname ФИО
 * @apiSuccess {String} response.users.auth_key API ключ
 * @apiSuccess {String} response.users.email E-mail
 * @apiSuccess {Object} response.users.status Статус
 * @apiSuccess {Integer} response.users.status.value Значение статуса
 * @apiSuccess {String} response.users.status.alias Название статуса
 * @apiSuccess {Integer} response.users.last_entering_date Дата последнего визита
 * @apiSuccess {Array} response.users.roles Список ролей
 * @apiSuccess {Object[]} response.users.actions Список действий
 * @apiSuccess {Integer} response.users.actions.id ID действия
 * @apiSuccess {String} response.users.actions.icon Иконка
 * @apiSuccess {String} response.users.actions.name Название
 * @apiSuccess {String} response.users.actions.type Тип
 * @apiSuccess {String} response.users.actions.method Метод
 * @apiSuccess {String} response.users.actions.url Ссылка на действие
 * @apiSuccess {Integer} response.count Общее кол-во моделей
 *
 * @apiUse SuccessRespond
 *
 * @apiUse ErrorRespond
 */

翻译

使用 Yii::t('app-sm-api-helpers', '') 对需要翻译的消息进行翻译。

sorokinmedia / yii2-api-helpers

维护者

详细信息