Обзор новой версии инструмента для разработки REST API на PHP 7.1+, с поддержкой OpenAPI спецификации для документирования и JSON Schema спецификации для валидации запросов и ответов.

Sunrise Router – маршрутизатор написанный на PHP, базирующийся на PSR-7 и PSR-15, с поддержкой аннотаций, и с недавнего времени, поддержкой OpenAPI спецификации и частично JSON Schema спецификации.

OpenAPI (в прошлом Swagger) – спецификация позволяющая описывать REST API (далее просто API), в том числе, принимаемые и возвращаемые структуры данных использую JSON Schema спецификацию (точнее ее расширенное подмножество).

JSON Schema – спецификация позволяющая описывать JSON структуры данных, в том числе, описывать правила валидации таких данных. Следовательно, имея JSON схему, набор данных и определенный инструмент (justinrainbow/json-schema), можно провалидировать такие данные.

Swagger (сегодня) – это инструментарий, служащий упростить разработку API, где самым примечательным, назовем его инструментом, я бы назвал Swagger UI, который в свою очередь, может стать для вас заменой таких REST клиентов, как Postman, Paw и т.д.

Мы затронули ряд спецификаций, но не упомянули JSON API спецификацию, о ней в статье речь не пойдет, однако если вы разработчик API, и вас тяготят сомнения, что отдаваемые вашим приложением структуры данных правильные, попробуйте ознакомится с выше упомянутой спецификацией.

Поддержка OpenAPI и JSON Schema спецификаций

В моем понимании, API должно быть задокументировано, и это ключевая проблема, точнее, на мой взгляд, проблема в переключении контекстов для разработчика.

Случай из практики: вы разработали некий контроллер в приложении, далее, вы переключаете контекст, описываете такой контроллер, допустим, в Postman или любом другом REST клиенте, далее, вы открываете некий README.md, где дополнительно описываете работу такого контроллера… Оставим за скобками процессы валидации, но вернемся к ним чуть позже… Вот только в какой-то момент, все пойдет не по плану, и документация не будет соответствовать действительно.

Рассмотрим другую ситуацию: вы в курсе выше упомянутых спецификаций, используете, допустим, инструмент zircote/swagger-php, и сталкиваетесь с несколькими проблемами:

1. Маршрутизация и пакет упомянутый выше ничего не знают друг о друге, я вынужден дублировать данные маршрутизации;
2. Описание объекта RequestBody несет исключительно информационный характер, я вынужден дублировать описание валидации на уровне кода;
3. Описание объекта Response несет исключительно информационный характер, я вынужден дублировать описание валидации, скажем, на уровне кода, но уже интеграционных тестов;
4. Reference Object ссылается в никуда, главное, чтобы это «никуда», было описано где-нибудь. Лично меня такой подход не устраивает;
5. Описание самого приложения происходит также как и описание, скажем, операций, то есть на уровне аннотаций. Лично меня такой подход, также не устраивает.

Что предлагает Sunrise Router:

1. Описывая контроллер, вы описываете его как операцию (Operation Object), опуская объекты Paths и Path Item, тем самым вы не дублируете имя маршрута, HTTP метод(ы), URI, атрибуты и правила их валидации;
2. Описание RequestBody объекта будет использовано для валидации запросов, путем конвертации OpenAPI Schema Object в JSON Schema Validation;
3. Описание Response объекта может быть использовано для валидации ответов на уровне интеграционных тестов за пределами приложения, путем конвертации OpenAPI Schema Object в JSON Schema Validation;
4. Reference Object ссылается на классы или их методы/свойства, кому-то это покажется логикой в аннотациях, для меня это равносильно конструкции @Entity(repositoryClass=""), то есть, нормальным явлением;
5. Описание самого приложения происходит уже на уровне кода, а не аннотаций.

Таким образом, в моем представлении, этапы разработки API могут быть следующие:

1. Вы создаете и описываете сущности без логики;
2. Вы создаете и описываете контроллеры возвращающие фейковые данные;
3. Зависимые от API люди могут включаться в работу, так как на этом этапе у нас имеется документация и валидация;
   
   • Front разработчик может приступать к реализации интерфейсов;
   • Тестер может начинать писать интеграционные тесты;
   • Вы спокойно реализуете логику в API, так как на этом этапе, в теории, все согласовано со всех сторон.

Считайте схему выше, не более чем, мыслями в слух, это примерно та схема, к которой я пытаюсь прийти сегодня. То есть, уделять больше времени именно проектированию, и договариваться с командой в процессе проектирования.

От теории к практике, типичный контроллер:

/**
 * @Route(
 *   name="api.entry.update",
 *   path="/api/v1/entry/{id<\d+>}",
 *   methods={"PATCH"},
 * )
 */
final class EntryUpdateController implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request) : ResponseInterface
    {
        return (new ResponseFactory)->createResponse(200);
    }
} 

Как видим, контроллер связан с маршрутом, который в свою очередь, имеет: имя, HTTP метод(ы), URI, атрибут id и регулярное выражение \d+ для его валидации. Теперь, не дублируя эти данные, опишем наш контроллер:

/**
 * @Route(...)
 *
 * @OpenApi\Operation(
 *   requestBody=@OpenApi\RequestBody(
 *     content={
 *       "application/json": @OpenApi\MediaType(
 *         schema=@OpenApi\Schema(
 *           type="object",
 *           required={"name"},
 *           properties={
 *             "name"=@OpenApi\Schema(
 *               type="string",
 *               minLength=1,
 *               maxLength=255,
 *               nullable=false,
 *             ),
 *           },
 *         ),
 *       ),
 *     },
 *   ),
 *   responses={
 *     200: @OpenApi\Response(
 *       description="OK",
 *     )
 *   },
 * )
 */
final class EntryUpdateController implements RequestHandlerInterface
{
    // some code...
}

Как видно из примера выше, мы имеем правило валидации для тела запроса, дублировать его, скажем в сервисе, я тоже не хочу, поэтому, я подключу промежуточное ПО:

/**
 * @Route(...,
 *   middlewares={
 *     "Sunrise\Http\Router\OpenApi\Middleware\RequestBodyValidationMiddleware",
 *   },
 * )
 *
 * @OpenApi\Operation(...)
 */
final class EntryUpdateController implements RequestHandlerInterface
{
    // some code...
}

Конечно, от валидации в коде избавиться полностью не удастся, но тем не менее, нам остается только проверить существование записи в хранилище.

use App\Controller\EntryUpdateController;
use Sunrise\Http\Router\OpenApi\Middleware\RequestBodyValidationMiddleware;

$collection->patch('api.entry.update', '/api/v1/entry/{id<\d+>}', new EntryUpdateController())
    ->addMiddleware(new RequestBodyValidationMiddleware());

Исходя из примеров выше, можно предположить, что схема свойства name может повторяться от контроллера к контроллеру, и дублировать такую информацию, мне бы тоже не хотелось. Поэтому я воспользуюсь Reference объектом...

Допустим, у нас имеется сущность Entry:

final class Entry
{

    /**
     * @OpenApi\Schema(
     *   refName="EntryName",
     *   type="string",
     *   minLength=1,
     *   maxLength=255,
     *   nullable=false,
     * )
     */
    private $name;
}

Теперь изменим описание нашего контроллера:

/**
 * @Route(...)
 *
 * @OpenApi\Operation(
 *   requestBody=@OpenApi\RequestBody(
 *     content={
 *       "application/json": @OpenApi\MediaType(
 *         schema=@OpenApi\Schema(
 *           type="object",
 *           required={"name"},
 *           properties={
 *             "name"=@OpenApi\SchemaReference(
 *               class="App\Entity\Entry",
 *               property="name",
 *             ),
 *           },
 *         ),
 *       ),
 *     },
 *   ),
 *   responses={
 *     200: @OpenApi\Response(
 *       description="OK",
 *     )
 *   },
 * )
 */
final class EntryUpdateController implements RequestHandlerInterface
{
    // some code...
}

Обратите внимание на аннотацию @OpenApi\SchemaReference(), объект Reference применим не только к схемам, но и ко всем другим объектам, которые допускает OpenAPI спецификация. Однако, если описание вам кажется все равно длинным, вы можете пойти дальше, и всю схему тела запроса вынести в метод, скажем, сервиса: EntryService::updateById(...)… Можно пойти еще дальше, и воспользоваться объектом RequestBodyReference… но я бы не стал выносить его за пределы контроллера… По личным соображениям, ограничений на этот счет никаких нет.

Больше примеров вы можете найти в репозитории скелетона, который доступен по ссылке.

Краткий список ключевых изменений в маршрутизаторе

• Контроллер теперь имплементирует RequestHandlerInterface, а не MiddlewareInterface – позволило отказаться от ResponseFactory из коробки и абстрагироваться от Sunrise PSR-7 implementation;
• Маршрут теперь имплементирует RequestHandlerInterface – позволило производить редиректы на уровне маршрутизатора;
• Маршрутизатор теперь наряду с прочим имплементирует MiddlewareInterface – дает больше возможностей для обработки ошибок и интеграции в уже существующую архитектуру;
• Маршрутизатор научился собирать URI маршрутов;
• Появилась возможность загрузки маршрутов из конфигов;
• Изменилась логика разбора URI, второй и выше уровень вложенности необязательных частей URI больше недопустим – ранее допускалась конструкция в виде /(foo/(bar/(baz))), сейчас это приведет к ошибке;
• Появилась возможность вешать промежуточное ПО (и не только) на группы.

Краткий список ключевых изменений в скелетоне

• Поставляется с воркером для RoadRunner и командой для генерации Systemd Unit – ранее использовался другой репозиторий;
• Изменена логика хранения конфигурационных файлов;
• Интегрирован Symfony Console компонент;
• Решена проблема с настройкой окружения для запуска тестов;
• Настроена обработка ошибок.

В игру «зачем писать это, когда есть это» можно играть бесконечно, но как бы там ни было, open-source все стерпит...

Спасибо всем кто принимал прямое или косвенное участие в разработке, особенно WinterSilence за его толчки в нужный момент!