grigor/yii2-generator

generator rest api

Maintainers

Details

github.com/cmkcmykmailru/yii2-generator

Source

Issues

Installs: 17

Dependents: 1

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

Type:yii2-extension

1.0.2 2021-03-07 23:34 UTC

Requires

Requires (Dev)

MIT b4875d3866947351bca4bb499398910b1237d794

  • grigor <cmk.cmyk.woop@mail.ru>

extensionyii2

This package is not auto-updated.

Last update: 2024-04-15 14:05:47 UTC

README

Генератор настроек rest api на основе аннотаций для расширения yii2-rest. По сути это утилита которая преобразует аннотации в коде в настройки которые нужны расширению yii2-rest. Она может использоваться в консоли и отдельно от нее, в зависимости от потребностей.

Установка

Предпочтительный способ установки этого расширения - через composer.

Запустите команду

php composer.phar require --prefer-dist grigor/yii2-generator "1.0.2"

или добавьте в composer.json

"grigor/yii2-generator": "^1.0.2",

Процесс настройки описан в расширении yii2-rest.

Система имеет две консольные команды

php yii generator/api/create
php yii generator/api/dev

Команда generator/api/create сканирует проект и ищет настройки в аннотациях, за тем конвертирует их для yii2-rest. В параметре можно указать путь сканируемой папки, тогда будет сканироваться не весь проект, а только указанная папка.

Вывод будет примерно таким:

Начал сканировать директорию: /var/www/users
Найден метод: api\repositories\SomeServiceOrRepository::getDemoContextMethod(...);         
              Route:       /v1/context/demo/<id:[\w\-]+>
              Method:      GET
              Context:     api\context\FindModel
              Response:    201

Найден метод: api\repositories\SomeServiceOrRepository::getPhone(...);
              Route:       /v1/shop/phones/<id:[\w\-]+>
              Method:      GET
              Serializer:  api\serializers\SerializePhone

Найден метод: api\repositories\SomeServiceOrRepository::getAllPhones(...);
              Route:       /v1/shop/phones
              Method:      GET
              Serializer:  api\serializers\SerializePhone

Найден метод: api\repositories\SomeServiceOrRepository::createPhone(...);
              Route:       /v1/shop/phones
              Method:      POST
              Response:    201

Найден метод: api\repositories\SomeServiceOrRepository::createAndReturnPhone(...);
              Route:       /v2/shop/phones
              Method:      POST
              Response:    201

Найден метод: api\repositories\SomeServiceOrRepository::updatePhone(...);
              Route:       /v1/shop/phones/<id:[\w\-]+>
              Method:      PUT
              Response:    202
              Serializer:  api\serializers\SerializePhone

Завершил.                                                                                                               

Целевых файлов:............1 шт.
Методов:...................6 шт.
Просканировано:............9933 файлов
Затрачено времени:.........3.805 сек.

Для того, чтобы аннотации работали в классе который их содержит нужно использовать:

use grigor\generator\annotation as API;

Пример аннотации:

    /**
     * @API\Route(
     *     url="/v1/shop/phones",
     *     methods={"GET"},
     *     alias="phones/index"
     * )
     * @API\Serializer("api\serializers\SerializePhone")
     * @return DataProviderInterface
     */
     public function getAllPhones(): DataProviderInterface

###Все настройки в аннотациях

####@Route

Route(
     url="/v1/shop/phones",
     methods={"GET"},
     alias="phones/index"
 )

url - адрес по который будет отрабатывать

methods - указываются методы GET POST PUT и т.д

alias - т.к. контроллеров как таковых нет для генерации url в коде нужно указывать такой alias используется этот алиас при генерации ссылок в коде Yii::$app->urlManager->createUrl(["phones/index"]); используется в штатном режиме.

####@Serializer

Serializer("api\serializers\SerializePhone")

Если вы хотите как-то по другому сериализовать возвращаемый объект можете указать калсс сериализатора. см. подробности yii2-rest.

####@Permission

Permission({"admin", "user"})

Если вам нужно ограничить доступ, то можно перечислить разрешения и роли.

####@Context

Context("api\context\FindModel")

Ограничитель области действия, можно так сказать, (типа как findModel). Вернуть он может массив с недостающими в отрабатывающем методе параметрами. Например у нас есть метод public function getProfile(string $id) а api-шка должна отдавать профиль текущего юзера. Т.е. для пользователя системы нет параметра id получается url примерно такой /v2/user/profile метод GET и все, но мы используем public function getProfile(string $id) где нужно передать id user-а в данном случае текущего. см. подробнее yii2-rest.

####@Response

Response(statusCode="202")

Если нужно вернуть статус код отличающийся от 200, то можно использовать такую аннотацию.

###Настройки Команда generator/api/dev сканирует папки указанные в настройках приложения например в common/config/params.php:

<?php
return [
    ...
    /**
     * Это пути где будут лежать настройки правил для рест апи и настройки методов которые будут отрабатывать в место actions.
     *
     * Если использовать yii2-generator, то лучше пути сразу писать без @alias или конвертировать
     * в относительный|реальный путь. Ниже будет описано почему или см. yii2-generator 
     * grigor\generator\tools\DeveloperTool::beforeAppRunScanDevDirectories($config);.
     */
    'serviceDirectoryPath' => Yii::getAlias('@api/data/static/services'),// тут будут лежать настройки методов.
    'rulesPath' => Yii::getAlias('@api/data/static/rules.php'), // тут сами правила со ссылками на настройки выше.
    /**
     * Параметр говорит генератору в каких папках ведется разработка ядра для апи, в общем случае где искать php файлы 
     * с аннотациями содержащими настройки для апи.
     * Этот параметр использует только yii2-generator, но он использует и параметры выше.
     */
    'devDirectories' => [
        Yii::getAlias('@api'),
    ]
    ...
];

При разработке удобно будет после каждого изменения аннотаций не набирать команды в консоли, для этого можно произвести следующие манипуляции с файлом index.php в папке api/web, именно до запуска приложения добавить такую строчку grigor\generator\tools\DeveloperTool::beforeAppRunScanDevDirectories($config); этот метод перегенерирует настройки перед запуском приложения. Все это дело может выглядеть следующим образом:

<?php

defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');

require __DIR__ . '/../../vendor/autoload.php';
require __DIR__ . '/../../vendor/yiisoft/yii2/Yii.php';
require __DIR__ . '/../../common/config/bootstrap.php';
require __DIR__ . '/../config/bootstrap.php';

$config = yii\helpers\ArrayHelper::merge(
    require __DIR__ . '/../../common/config/main.php',
    require __DIR__ . '/../../common/config/main-local.php',
    require __DIR__ . '/../config/main.php',
    require __DIR__ . '/../config/main-local.php'
);
/*
//этот вариант подойдет если вы держите настройки rest api в базе.
if (!exec('cd ../../ && php yii generator/api/dev')) {
    throw \RuntimeException('Что то пошло не так.');
}
*/

grigor\generator\tools\DeveloperTool::beforeAppRunScanDevDirectories($config);
(new yii\web\Application($config))->run();

Данные манипуляции можно использовать только в момент разработки, не забудьте на продакшене удалить эту строчку или настройте environments. Хоть система работает быстро, если у вас очень много методов c api (переваливает за тысячи :)) и начинает подтормаживать, то в конфиге можно сократить кол-во сканируемых папок (переключиться на текущую).

Тестировать

composer tests