Skip to content

Latest commit

 

History

History
251 lines (188 loc) · 12.7 KB

README.RU.md

File metadata and controls

251 lines (188 loc) · 12.7 KB

Swagger Resolver Bundle In English

PHPUnit Coverage Status Latest Stable Version Total Downloads

При возникновении вопросов можно связаться по email или через Telegram.

Пример использования на GitHub Gist

Введение

Бандл предоставляет возможность валидировать данные в соответствии с описанной документацией 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.

Запуск тестов и инструментов статического анализа

Скачать проект:

git clone git@github.com:adrenalinkin/swagger-resolver-bundle.git
cd swagger-resolver-bundle

Пройти по инструкции для настройки простого docker контейнера.

Установить Composer зависимости:

composer update

Для запуска тестов выполнить:

bin/simple-phpunit

Для запуска PHP-CS-Fixer выполнить:

php-cs-fixer fix --diff

Для запуска composer-normalize выполнить:

composer-normalize --dry-run

Лицензия

license