README.RU.md

Swagger Resolver Bundle

WARNING: This repo is no longer actively maintained

Введение

Бандл предоставляет возможность валидировать данные в соответствии с описанной документацией Swagger 2. Единожды описав документацию api при помощи swagger вы получаете проверку данных на соответствие описанным требованиям. Обновляется документаци - обновляются требования, все в одном месте!

Документация кэшируется посредством стандартного механизма Symfony Warmers. В режиме отладки кэш автоматически прогревается если изменить файл, содержащий описание документации.

Примечание: в качестве ответа приходит объект SwaggerResolver расширение для OptionsResolver. Таким образом вы получаете полный контроль над созданным набором требований к данным.

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

Интеграции

Бандл предоставляет автоматическую интеграцию с NelmioApiDocBundle, поддерживает загрузку конфигурации из swagger-php, а также загрузку конфигурации непосредственно из файла json или yaml(yml). При отсутствии дополнительной конфигурации бандл автоматически подключит самый оптимальный доступный способ загрузки конфигурации. Порядок приоритета:

1. NelmioApiDocBundle - не требует дополнительной конфигурации.
2. swagger-php - По умолчанию сканирует папку src/. Использует параметры swagger_php.scan иswagger_php.exclude.
3. json - По умолчанию ищет файл web/swagger.json. Использует параметр configuration_file.

Установка

Шаг 1: Загрузка бандла

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

    composer require adrenalinkin/swagger-resolver-bundle

Эта команда подразумевает что Composer установлен и доступен глобально.

Шаг 2: Подключение бандла

После включите бандл добавив его в список зарегистрированных бандлов в app/AppKernel.php файл вашего проекта:

<?php declare(strict_types=1);
// app/AppKernel.php

class AppKernel extends Kernel
{
    // ...

    public function registerBundles()
    {
        $bundles = [
            // ...

            new Linkin\Bundle\SwaggerResolverBundle\LinkinSwaggerResolverBundle(),
        ];

        return $bundles;
    }

    // ...
}

Конфигурация

Чтобы начать использовать бандл не требуется предварительной конфигурации. Все параметры имеют значения по умолчанию:

# app/config.yml
linkin_swagger_resolver:
    # список локаций параметров по умолчания, для которых включена нормализация
    enable_normalization:
        - 'query'
        - 'path'
        - 'header'
    # стратегия для слияния параметров запроса
    path_merge_strategy:            Linkin\Bundle\SwaggerResolverBundle\Merger\Strategy\StrictMergeStrategy
    configuration_loader_service:   ~   # имя сервиса загрузки конфигурации
    configuration_file:             ~   # полный путь к файлу конфигурации
    swagger_php:                        # настройки для swagger-php
        scan:       ~                   # массив полных путей для сканирования аннотаций
        exclude:    ~                   # массив полных путей которые стоит исключить

Использование

Шаг 1: Подготовка swagger документации

Подготовка swagger документации отличается в зависимости от используемых инструментов в вашем проекте.

NelmioApiDocBundle

Если в вашем проекте подключен NelmioApiDocBundle то дополнительная конфигурация не требуется.

swagger-php

В случае отсутствия NelmioApiDocBundle бандл деградирует до загрузки конфигурации на основании аннотаций swagger-php. При этом для сканирования будет использована директория проекта src/. Чтобы оптимизировать сканирование вы можете указать директории явно:

# app/config.yml
linkin_swagger_resolver:
    swagger_php:
        scan:
            - '%kernel.project_dir%/src/Acme/ApiBundle'
        exclude:
            - '%kernel.project_dir%/src/Acme/ApiBundle/Resources'
            - '%kernel.project_dir%/src/Acme/ApiBundle/Repository'

JSON

В случае отсутствия NelmioApiDocBundle и swagger-php бандл деградирует до загрузки конфигурации из json файла. По умолчанию происходит поиск файла web/swagger.json. Вы также можете указать путь к файлу с конфигурацией:

# app/config.yml
linkin_swagger_resolver:
    configuration_file: '%kernel.project_dir%/web/swagger.json' # обязательно расширений файла json

YAML or (yml)

В случае отсутствия NelmioApiDocBundle и swagger-php и наличия конфигурации в формате yaml (yml) вам необходимо указать полный путь к файлу в конфигурации бандла:

# app/config.yml
linkin_swagger_resolver:
    configuration_file: '%kernel.project_dir%/web/swagger.yaml' # обязательно расширений файла yaml или yml

Custom

При необходимости использовать собственный загрузчик вам необходимо реализовать требуемое поведение в классе, реализующем интерфейс SwaggerConfigurationLoaderInterface. После чего необходимо указать название сервиса этого класса в конфигурации:

# app/config.yml
linkin_swagger_resolver:
    configuration_loader_service: acme_app.custom_configuration_loader

Шаг 2: Валидация данных

Валидация модели

<?php declare(strict_types=1);

/** @var \Linkin\Bundle\SwaggerResolverBundle\Factory\SwaggerResolverFactory $factory */
$factory = $container->get('linkin_swagger_resolver.factory');
// загрузка по полному имени класса модели
$swaggerResolver = $factory->createForDefinition(AcmeApiModel::class);
// загрузка имени класса модели
$swaggerResolver = $factory->createForDefinition('AcmeApiModel');

/** @var \Symfony\Component\HttpFoundation\Request $request */
$data = $swaggerResolver->resolve(json_decode($request->getContent(), true));

Валидация всего запроса

<?php declare(strict_types=1);

/** @var \Linkin\Bundle\SwaggerResolverBundle\Factory\SwaggerResolverFactory $factory */
$factory = $container->get('linkin_swagger_resolver.factory');
$request = $container->get('request_stack')->getCurrentRequest();
// загрузка всех параметров вызванного метода запроса
$swaggerResolver = $factory->createForRequest($request);

$data = $swaggerResolver->resolve(json_decode($request->getContent(), true));

Дополнительно

Собственный валидатор

Бандл производит валидацию данных посредством системы валидаторов. Со списком всех валидаторов вы можете ознакомиться перейдя в папку Validator. Валидаторы являются тегированными сервисами. Чтобы создать свой собственный валидатор достаточно создать класс, реализующий интерфейс SwaggerValidatorInterface и зарегистрировать его с тегом linkin_swagger_resolver.validator.

Собственный нормализатор

Бандл производит нормализацию данных посредством системы нормализаторов. Со списком всех нормализаторов вы можете ознакомиться перейдя в папку Normalizer. Нормализаторы являются тегированными сервисами. Чтобы создать свой собственный нормализатор достаточно создать класс, реализующий интерфейс SwaggerNormalizerInterface и зарегистрировать его с тегом linkin_swagger_resolver.normalizer.

Лицензия