flight php swagger

Пакет «Полет/Чувство»

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

Начиная

Предварительные условия

В этом руководстве предполагается, что вы в настоящее время используете (или планируете использовать) в своем проекте следующие технологии:

• PHP 7.1+

• Композитор

• Xdebug (требуется, если вы планируете использовать PHPUnit)

Установка

1. Во-первых, убедитесь, что вы установили и настроили работающий веб-сервер (например, Apache) с PHP 7.1 или выше.

2. Используйте composer , чтобы загрузить скелет проекта, установить все необходимые зависимости и запустить примеры модульных тестов:

   composer create-project tribeos/flight-php-swagger path/to/project

Включить перезапись URL-адресов

Поскольку работа Flight зависит от модуля mod_rewrite Apache 2, вам следует сначала включить его через a2enmod , а затем перезапустить сервер:

sudo a2enmod rewrite

sudo systemctl restart apache2

После этого вам также следует отредактировать файл конфигурации Apache по умолчанию, поскольку он изначально запрещает использование файла .htaccess для применения правил перезаписи. Файл конфигурации обычно находится по адресу /etc/apache2/apache2.conf . В нем найдите блок, ссылающийся на каталог /var/www и убедитесь, что для AllowOverride установлено значение All и что для Require all granted установлено значение «Все».

 <Directory /var/www/>Параметры Индексы FollowSymLinksAllowOverride AllRequire все разрешено
</Каталог>

После сохранения изменений перезапустите сервер Apache.

Если у вас есть или вы хотите иметь несколько конфигураций сайта, вы также можете включить правила перезаписи для каждого сайта, отредактировав нужный файл конфигурации в /etc/apache2/sites-available . Для получения дополнительной информации вы можете обратиться к следующему руководству.

Примечание . Вышеупомянутые инструкции предполагают, что вы используете дистрибутив Ubuntu. Если вы используете другую операционную систему, обратитесь к соответствующему руководству по включению модуля перезаписи.

• Windows (WAMP/XAMPP)

• ЦентОС

Установите недостающие расширения PHP

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

Проблема	Решение
mbstring	sudo apt install php-mbstring
проблемы, связанные с zip и unzip	sudo apt install zip unzip php-zip

Примечание . Как и в предыдущем разделе Apache 2, эти инструкции относятся к дистрибутивам Ubuntu. Если вы используете другую операционную систему, обратитесь к соответствующей альтернативной команде.

Структура проекта

После завершения установки вы увидите в своем проекте следующую структуру:

path/to/project
├── app 
│   ├── models
│   │   └── SampleModel.php
│   ├── routes
│   │   ├── FlightSetup.php
│   │   └── SampleRoute.php
│   └── utils
│       └── Validator.php
├── config
│   ├── config.php
│   └── config.sample.php
├── docs
├── logs
│   └──  .htaccess
├── tests
│   ├── build
│   └── unit
│       └── SampleTest.php
├── vendor
├── .gitignore
├── .htaccess
├── autoload.php
├── composer.json
├── composer.lock
├── index.php
├── LICENSE
├── phpunit.xml
└── README.md

Краткое изложение основных компонентов проекта:

• app : основная папка приложения

• models : модели, используемые для запросов/ответов.

• routes : определение маршрутов API

• utils : утилиты приложения, такие как валидаторы и регистраторы.

• config : файл(ы) конфигурации

• docs : файлы документации Swagger.

• logs : хранилище журналов

• tests : папка тестов приложения

• build : любые скомпилированные файлы, полученные в результате тестов формы (покрытие кода и т. д.)

• src : проверить исходные файлы

• vendor : расположение всех библиотек и стороннего кода

• autoload.php : файл начальной загрузки, который загружает зависимости Composer и включает все остальные файлы проекта.

• index.php : точка входа API

• phpunit.xml : конфигурация тестирования PHPUnit.

Работа над проектом

Конфигурация проекта

Вся основная конфигурация, связанная с проектом (и документация Swagger), хранится в файле config/config.php . Измените/добавьте константы конфигурации в соответствии с потребностями вашего проекта.

Еще один важный файл — index.php , который служит точкой входа в API. Для этого требуется файл autoload.php , который содержит код для загрузки зависимостей Composer, а также все другие необходимые файлы проекта. Более того, он запускает фреймворк Flight. Файлы, импортированные по умолчанию, — это все models , routes и utils , а также файл конфигурации проекта ( config/config.php ), файл конфигурации Swagger-PHP ( docs/swagger.php ) и vendor/autoload.php . Измените/добавьте файлы для импорта в соответствии с потребностями вашего проекта.

Полет

Flight — это расширяемая и простая в использовании платформа PHP, которая позволяет быстро создавать веб-API RESTful. Он позволяет создавать подробные и функциональные конечные точки API в сочетании с функциями промежуточного программного обеспечения и возможностью переопределять/создавать собственные методы.

 Flight::route('GET /sample/@value', function($value) {
    Flight::json([ 'sample_value' => $value ]);
});

Вся маршрутизация в проекте осуществляется через Flight. Первоначальная настройка полета ( FlightSetup.php ), а также все маршруты проекта хранятся в папке routes и могут быть изменены в соответствии с вашими потребностями.

Подробную документацию по использованию и примеры Flight можно найти на главной странице Flight в разделе «Изучение». Для получения более подробной информации о самой платформе Flight вы можете посетить ее репозиторий GitHub.

Swagger-PHP

После создания маршрута в папке routes вы можете приступить к написанию и созданию документации OpenAPI для вашего RESTful API.

Документация записывается внутри DocBlocks , также известных как блоки комментариев PHP, над соответствующим маршрутом.

 /** * @OAGet( * path="/sample/route", * tags={"sample"}, * summary="Пример маршрута.", * @OAResponse( * response=200, *description="A пример ответа." * ), * Security={ * {"api_key": {}} * } * )*/

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

Общую конфигурацию Swagger, такую ​​как имя проекта, автор(ы) проекта, URL-адрес сервера API, папки спецификаций и т. д., можно найти и настроить в config/config.php в области «Константы конфигурации Swager» .

Скелет проекта поставляется вместе с папкой docs , в которой хранятся все необходимые файлы для документации Swagger (файлы настройки PHP, HTML и CSS). Доступ к документации осуществляется путем перехода к корневому маршруту ( / ) вашего проекта через браузер.

Для получения дополнительной информации о Swagger в целом и стандарте OpenAPI посетите официальную домашнюю страницу Swagger. Обширную документацию по использованию и примеры реализации PHP можно найти на официальной домашней странице swagger-php.

Коммунальные услуги проекта

Регистратор

Проект поставляется в комплекте с http-logger, который представляет собой регистратор HTTP-запросов, ответов и ошибок, который (по умолчанию) регистрирует каждый входящий запрос и соответствующий ответ в logs/debug.log в виде значений, разделенных табуляцией (TSV). Подробную информацию о регистраторе и сведения о конфигурации можно найти на его странице GitHub.

Регистратору требуется местоположение файла журнала (который по умолчанию настраивается через константу в config/config.php ). Более того, чтобы полностью использовать возможности регистратора, внутренний обработчик ошибок Flight должен быть отключен (если он включен, он будет перехватывать определенные типы ошибок до http-logger).

 /* Отключить внутренний регистратор ошибок FlightPHP. */Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* Получить и использовать регистратор */$logger = HttpLogger::get();$logger->log();

Регистратор включается через routes/FlightSetup.php и настраивается внутри функции промежуточного программного обеспечения Flight::after() , которая запускается после каждого запроса (чтобы она могла получить соответствующий ответ). Вы можете изменить функции регистратора, а также маршруты, которые он будет отслеживать, по вашему запросу.

Flight::output()

Flight::output() — это настраиваемый сопоставленный метод, который сочетает в себе функции Flight::json() (вывод ответа JSON) и настраиваемого HTTP Logger. Любой ответ API, отправленный с помощью этого метода, будет автоматически регистрироваться в соответствии с настройками, установленными в средстве ведения журнала. Метод определен и настроен в routes/FlightSetup.php .

Это полезно, если вам нужна функция ведения журнала для ваших пар запрос/ответ без использования промежуточного программного обеспечения Flight для перехвата.

Flight::output() принимает два параметра: фактические данные для отправки ( обязательный ) и код ответа ( необязательный , по умолчанию 200).

 Flight::output(['sample_message' => 'Пример ответа.'], 301);

Flight::validate()

Flight::validate() использует аналитику Swagger-PHP, чтобы определить, является ли переданное тело запроса действительным (содержащим все необходимые атрибуты) в соответствии с ожидаемой спецификацией модели OpenAPI.

Все модели объявлены как классы, а их атрибуты установлены как общедоступные. Модели определены в app/models и имеют следующую структуру:

 /** * @OASchema( * ) */class SampleModel {/** * @OAProperty( *description="Пример атрибута тела запроса.", * example="Пример строки." * require=true * ) * @ строка вар */public $sample_attribute;
}

В этом конкретном примере description используется для краткого обзора свойства модели, required определяет, является ли свойство обязательным или нет, а example присваивает ему значение по умолчанию. Дополнительные сведения о схемах моделей см. в документации Swagger-PHP.

Класс валидатора модели объявлен и определен в utils/Validator.php и включен как настраиваемый сопоставленный метод Flight в routes/FlightSetup.php . Он принимает два параметра: класс, по которому должно проверяться тело запроса, и само тело запроса.

 Flight::validate(SampleModel::class, Flight::request()->data->getData());

Этот метод следует вызывать внутри маршрута API до вызова каких-либо дополнительных методов. Если модель действительна, запрос продолжит выполнение. Если модель не проходит проверку, она выводит код ответа 400 Bad Request , завершая запрос.

Примечание . Flight::validate() зависит от Flight::output() , поэтому, если вы планируете удалить пользовательский метод вывода из проекта, вам следует переписать сопоставленный метод валидатора по мере необходимости.

Тестирование проекта

В состав проекта входит PHPUnit, среда тестирования для PHP, которая, помимо самого тестирования, также позволяет генерировать покрытие кода.

Тестовая установка

Все настройки, связанные с тестированием с помощью PHPUnit, находятся в phpunit.xml . Для настройки доступно несколько вариантов:

1. Расположение тестовых файлов Внутри тега testsuites можно определить местоположение, которое будет сканироваться на наличие тестов. По умолчанию tests/unit . Когда тестовый каталог определен (через тег directory ), тестовые файлы будут запускаться в алфавитном порядке во время выполнения теста. При необходимости мы также можем определить тестовые файлы в индивидуальном порядке с помощью тега file .

    <тестовые наборы>
        <testsuite name="sample-test-suite">
            <directory suffix="Test.php">tests/src/</directory><! -- По умолчанию тестовые файлы будут запускаться в алфавитном порядке. Если вы хотите установить определенный порядок выполнения, определите отдельные тестовые файлы --><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
    </testsuites>

2. Типы отчетов о тестовом покрытии После запуска тестов можно создавать различные типы отчетов о тестировании. Типы журналов определяются в теге logging . Все скомпилированные тестовые файлы по умолчанию расположены внутриtests tests/build .

    <logging><!-- Типы журналов тестирования --><log type="testdox-html" target="tests/build/testdox.html"/>
        <log type="tap" target="tests/build/report.tap"/>
        <log type="junit" target="tests/build/report.junit.xml"/>
        <log type="coverage-html" target="tests/build/coverage"/>
        <log type="coverage-text" target="tests/build/coverage.txt"/>
        <log type="coverage-clover" target="tests/build/logs/clover.xml"/>
    </ведение>

3. Файлы, которые будут включены или исключены из отчета о покрытии кода. Вы также можете выбрать, какие файлы будут включены в отчет о покрытии кода (или исключены из него). Это делается с помощью тега filter внутри тега whitelist . По умолчанию настройка PHPUnit проекта охватывает файлы в каталоге app , исключая models и routes (поскольку эти папки не содержат код, который можно эффективно протестировать на предмет покрытия кода). Вы также можете определить свои собственные папки и файлы включения/исключения.

    <фильтр>
        <whitelist><!-- Имя папки, которая будет использоваться для покрытия кода --><directory suffix=".php">app/</directory>
            <exclude><!-- Файлы/папки, исключенные из покрытия кода (PHP-файлы без тестируемых методов). Отредактируйте в соответствии с потребностями вашего проекта. --><directory suffix=".php">app/models</directory>
                <directory suffix=".php">приложение/маршруты</directory>
            </исключить>
        </белый список>
    </фильтр>

Написание тестов

Все модульные тесты по умолчанию должны быть записаны в tests/unit . Имена тестовых файлов должны заканчиваться на Test.php , чтобы PHPUnit мог их обнаружить (как определено в phpunit.xml ), например SampleTest.php .

Тестовый класс определяется как расширение класса TestCase и может включать в себя различные методы тестирования. При именовании тестов вы можете использовать следующее соглашение: test + описание теста в верблюжьем регистре (например, testThisIsASampleTest ). Это позволит преобразовать имя тестового примера в описательное предложение во время выполнения теста, предоставляя разработчику дополнительную информацию о том, что должен делать тест.

 /*tests/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest расширяет TestCase {public function testThisIsASampleTest() {$this->assertTrue(true);
    }
}

Выполнение теста

Чтобы выполнить все тесты, запуститеvendor vendor/bin/phpunit --testdox в корневом каталоге проекта.

 root@ubuntu:/path/to/project$vendor/bin/phpunit --testdox
PHPUnit 7.5.16 от Себастьяна Бергманна и его участников.

Образец
  Это образец теста

Чтобы запустить только один тестовый файл, укажите его путь: vendor/bin/phpunit --testdox tests/unit/SampleTest.php

Флаг --testdox не является обязательным, но рекомендуется, так как он будет генерировать описательные предложения о тестах на основе их названий (как обсуждалось в разделе выше), что упрощает понимание того, что происходит внутри тестов.

После выполнения тестов отчет о покрытии кода создается в каталогеtests tests/build/coverage , и его можно просмотреть, открыв этот путь в браузере.

Авторы

• Алдин Ковачевич , первоначальная работа над скелетом и документацией — Aldin-SXR

Лицензия

Скелет лицензирован по лицензии MIT. Подробности смотрите в файле ЛИЦЕНЗИИ.

---

Работа продолжается.