flight php swagger
v0.6.2
Micro-framework de vol fourni avec Swagger, PHPUnit et d'autres utilitaires utiles. Conçu pour aider à démarrer le développement d'API construites avec les outils susmentionnés en incluant la configuration de base du projet, les itinéraires et les modèles de test, ainsi que le modèle pour les tests unitaires.
Ce guide suppose que vous utilisez actuellement (ou prévoyez d'utiliser) les technologies suivantes dans votre projet :
PHP7.1+
Compositeur
Xdebug (obligatoire si vous prévoyez d'utiliser PHPUnit)
Tout d'abord, assurez-vous d'avoir installé et configuré un serveur Web en cours d'exécution (tel qu'Apache) avec PHP 7.1 ou supérieur.
Utilisez composer pour télécharger le squelette du projet, installer toutes les dépendances requises et exécuter les exemples de tests unitaires :
composer create-project tribeos/flight-php-swagger path/to/project
Puisque Flight dépend du module mod_rewrite d'Apache 2 pour fonctionner, vous devez d'abord l'activer via a2enmod puis redémarrer le serveur :
sudo a2enmod rewrite
sudo systemctl restart apache2
Ensuite, vous devez également modifier le fichier de configuration par défaut d'Apache, car il interdit initialement l'utilisation d'un fichier .htaccess pour appliquer des règles de réécriture. Le fichier de configuration se trouve généralement dans /etc/apache2/apache2.conf . Dans celui-ci, localisez le bloc faisant référence au répertoire /var/www et assurez-vous que AllowOverride est défini sur All et que vous Require all granted .
<Répertoire /var/www/>Options Index FollowSymLinksAllowOverride AllRequire tous accordés </Répertoire>
Après avoir enregistré les modifications, redémarrez le serveur Apache.
Si vous disposez ou souhaitez disposer de plusieurs configurations de sites, vous pouvez également activer les règles de réécriture pour chaque site, en modifiant le fichier de configuration souhaité dans /etc/apache2/sites-available . Vous pouvez vous référer au didacticiel suivant pour plus d'informations.
Remarque : Les instructions ci-dessus supposent que vous utilisez une distribution Ubuntu. Si vous utilisez un autre système d'exploitation, veuillez vous référer au didacticiel approprié sur l'activation du module de réécriture.
Windows (WAMP/XAMPP)
CentOS
Le projet et ses dépendances nécessitent l'installation de certaines extensions PHP. Les extensions courantes qui pourraient vous manquer pourraient être les suivantes :
| Problème | Solution |
|---|---|
mbstring | sudo apt install php-mbstring |
problèmes liés zip et unzip | sudo apt install zip unzip php-zip |
Remarque : Comme pour la section Apache 2 précédente, ces instructions concernent les distributions Ubuntu. Reportez-vous à une commande alternative appropriée si vous utilisez un système d'exploitation différent.
Une fois l'installation terminée, vous retrouverez cette structure dans votre projet :
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
Aperçu des principales composantes du projet :
app : le dossier principal de l'application
models : modèles utilisés pour les requêtes/réponses
routes : définition des routes API
utils : utilitaires d'application, tels que les validateurs et les enregistreurs
config : fichier(s) de configuration
docs : fichiers de documentation Swagger
logs : stockage des logs
tests : dossier des tests d'application
build : tous les fichiers compilés résultant de tests (couverture de code, etc.)
src : tester les fichiers sources
vendor : emplacement de toutes les bibliothèques et du code tiers
autoload.php : Un fichier d'amorçage qui charge les dépendances de Composer et inclut tous les autres fichiers du projet
index.php : point d'entrée de l'API
phpunit.xml : configuration des tests PHPUnit
Toute la configuration principale liée au projet (et la documentation Swagger) est gérée dans le fichier config/config.php . Modifiez/ajoutez les constantes de configuration en fonction des besoins de votre projet.
Un autre fichier important est index.php , qui sert de point d'entrée à l'API. Il nécessite le fichier autoload.php , qui contient le code pour charger les dépendances de Composer, ainsi que tous les autres fichiers de projet nécessaires. De plus, il démarre le framework Flight. Les fichiers importés par défaut sont tous models , routes et utils , ainsi que le fichier de configuration du projet ( config/config.php ), le fichier de configuration Swagger-PHP ( docs/swagger.php ) et le vendor/autoload.php du Composer. Modifiez/ajoutez des fichiers à importer en fonction des besoins de votre projet.
Flight est un framework PHP extensible et facile à utiliser qui permet de créer rapidement des API Web RESTful. Il vous permet de créer des points de terminaison d'API détaillés et fonctionnels, associés à des fonctionnalités middleware et à la possibilité de remplacer/créer des méthodes personnalisées.
Flight::route('GET /sample/@value', function($value) {
Flight::json([ 'sample_value' => $value ]);
}); Tout le routage du projet se fait via Flight. La configuration initiale du vol ( FlightSetup.php ), ainsi que toutes les routes du projet sont gérées dans le dossier routes et peuvent être modifiées en fonction de vos besoins.
Une documentation d'utilisation complète et des exemples sur Flight sont disponibles sur la page d'accueil de Flight - zone « Apprendre ». Pour plus de détails sur le framework Flight lui-même, vous pouvez visiter son référentiel GitHub.
Après avoir créé une route dans le dossier routes , vous pouvez commencer à rédiger et générer de la documentation OpenAPI pour votre API RESTful.
La documentation est écrite dans les DocBlocks , alias blocs de commentaires PHP, au-dessus de la route correspondante.
/** * @OAGet( * path="/sample/route", * tags={"sample"}, * summary="Un exemple de route.", * @OAResponse( * réponse=200, * description="A exemple de réponse." * ), * security={ * {"api_key": {}} * } * )*/Vous pouvez définir le chemin, les balises, un bref résumé, les paramètres, les valeurs des paramètres par défaut, le corps de la demande, les réponses disponibles, l'authentification de sécurité et de nombreuses autres options pour chaque point de terminaison RESTful.
La configuration générale de Swagger, telle que le nom du projet, les auteurs du projet, l'URL du serveur API, les dossiers de spécifications, etc., peut être trouvée et configurée dans config/config.php , sous la zone "Constantes de configuration Swager" .
Le squelette du projet est accompagné du dossier docs , qui contient tous les fichiers nécessaires à la documentation Swagger (fichiers d'installation PHP, HTML et CSS). La documentation est accessible en accédant à la route racine ( / ) de votre projet via un navigateur.
Pour plus d'informations sur Swagger en général et sur la norme OpenAPI, reportez-vous à la page d'accueil officielle de Swagger. Une documentation d'utilisation complète et des exemples concernant l'implémentation de PHP sont disponibles sur la page d'accueil officielle de swagger-php.
Le projet est fourni avec http-logger, qui est un enregistreur de requêtes, de réponses et d'erreurs HTTP, qui enregistrera (par défaut) chaque requête entrante et sa réponse correspondante dans logs/debug.log , sous forme de valeurs séparées par des tabulations (TSV). Des informations détaillées sur l'enregistreur et les détails de configuration sont disponibles sur sa page GitHub.
Le logger nécessite l'emplacement du fichier journal (qui est configuré par défaut via une constante dans config/config.php ). De plus, afin d'utiliser pleinement les capacités de l'enregistreur, le gestionnaire d'erreurs interne de Flight doit être désactivé (s'il est activé, il détectera certains types d'erreurs avant http-logger).
/* Désactive l'enregistreur d'erreurs interne de FlightPHP. */Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* Récupère et utilise le logger */$logger = HttpLogger::get();$logger->log(); L'enregistreur est inclus via routes/FlightSetup.php et configuré dans la fonction middleware Flight::after() , qui s'exécute après chaque requête (il est donc capable de récupérer la réponse appropriée). Vous pouvez modifier les fonctionnalités de l'enregistreur, ainsi que les itinéraires qu'il surveillera, à votre demande.
Flight::output() Flight::output() est une méthode mappée personnalisée qui combine les fonctionnalités de Flight::json() (sortie de réponse JSON) et du HTTP Logger personnalisé. Toute réponse API envoyée via cette méthode sera automatiquement enregistrée, selon les préférences définies dans l'enregistreur. La méthode est définie et configurée dans routes/FlightSetup.php .
Ceci est utile lorsque vous souhaitez bénéficier de la fonctionnalité de journalisation pour vos paires demande/réponse sans utiliser le middleware Flight pour l'intercepter.
Flight::output() prend deux paramètres : les données réelles à envoyer ( obligatoire ) et le code de réponse ( facultatif , 200 par défaut).
Flight::output(['sample_message' => 'Exemple de réponse.'], 301);
Flight::validate() Flight::validate() utilise l'analyse Swagger-PHP pour déterminer si un corps de requête transmis est valide (contenant tous les attributs requis) conformément à la spécification attendue du modèle OpenAPI.
Tous les modèles sont déclarés comme classes et leurs attributs sont définis sur public. Les modèles sont définis dans app/models et suivent cette structure :
/** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * description="Exemple d'attribut du corps de la requête.", * example="Exemple de chaîne." * requis=true * ) * @ var chaîne */public $sample_attribute;
} Dans cet exemple concret, description est utilisée pour donner un bref aperçu de la propriété du modèle, required détermine si la propriété est obligatoire ou non, et example lui attribue une valeur par défaut. Pour plus d'informations sur les schémas de modèle, reportez-vous à la documentation Swagger-PHP.
La classe du validateur de modèle est déclarée et définie dans utils/Validator.php , et incluse en tant que méthode Flight mappée personnalisée dans routes/FlightSetup.php . Il prend deux paramètres : la classe par rapport à laquelle le corps de la requête doit être validé et le corps de la requête lui-même.
Flight::validate(SampleModel::class, Flight::request()->data->getData());
La méthode doit être appelée dans une route API, avant que des méthodes supplémentaires ne soient appelées. Si le modèle est valide, la requête se poursuivra avec l'exécution. Si le modèle ne parvient pas à être validé, il générera un code de réponse 400 Bad Request , mettant ainsi fin à la requête.
Remarque : Flight::validate() dépend de Flight::output() , donc si vous envisagez de supprimer la méthode de sortie personnalisée du projet, vous devez réécrire la méthode mappée du validateur si nécessaire.
Le projet est livré avec PHPUnit, un framework de test pour PHP qui, en plus de se tester lui-même, permet également de générer une couverture de code.
Toute la configuration liée aux tests avec PHPUnit se trouve dans phpunit.xml . Plusieurs options sont disponibles pour la configuration :
L'emplacement des fichiers de test À l'intérieur de la balise testsuites , l'emplacement qui sera analysé pour les tests peut être défini. Par défaut, il s'agit tests/unit . Lorsqu'un répertoire de test est défini (via la balise directory ), les fichiers de test seront exécutés par ordre alphabétique lors de l'exécution du test. Si nécessaire, nous pouvons également définir les fichiers de test dans un ordre personnalisé via la balise file .
<suites de tests>
<nom de la suite de tests="sample-test-suite">
<directory suffix="Test.php">tests/src/</directory><!-- Par défaut, les fichiers de test seront exécutés dans l'ordre alphabétique des fichiers. Si vous souhaitez définir un ordre d'exécution spécifique, définissez des fichiers de test individuels--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
</suites de tests> Types de rapports de couverture de test Différents types de rapports de test peuvent être générés une fois les tests exécutés. Les types de journaux sont définis dans la balise logging . Tous les fichiers de test compilés sont, par défaut, situés dans tests/build .
<logging><!-- Types de journaux de tests --><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"/>
</logging> Fichiers à inclure/exclure de la couverture de code Vous pouvez également choisir quels fichiers seront inclus (ou exclus) du rapport de couverture de code. Cela se fait via la balise filter , à l’intérieur de la balise whitelist . Par défaut, la configuration PHPUnit du projet couvre les fichiers du répertoire app , à l'exclusion models et routes (car ces dossiers ne contiennent pas de code pouvant être testé efficacement pour la couverture du code). Vous pouvez également définir vos dossiers et fichiers d'inclusion/exclusion personnalisés.
<filtre>
<whitelist><!-- Le nom du dossier à utiliser pour la couverture du code --><directory suffix=".php">app/</directory>
<exclude><!-- Fichiers/dossiers exclus de la couverture du code (fichiers PHP sans méthodes testables). Modifiez en fonction des besoins de votre projet. --><directory suffix=".php">app/models</directory>
<directory suffix=".php">app/routes</directory>
</exclure>
</liste blanche>
</filtre> Tous les tests unitaires doivent être, par défaut, écrits dans le répertoire tests/unit . Les noms de fichiers de test doivent se terminer par Test.php , afin qu'ils puissent être découverts par PHPUnit (tel que défini dans phpunit.xml ), par exemple SampleTest.php .
Une classe de test est définie comme une extension de la classe TestCase et peut inclure diverses méthodes de test. Lors de la dénomination des tests, vous pouvez utiliser la convention suivante : test + description du test en cas camel (par exemple testThisIsASampleTest ). Cela permettra au nom du scénario de test d'être converti en une phrase descriptive pendant l'exécution du test, donnant ainsi au développeur un aperçu supplémentaire de ce que le test doit faire.
/* tests/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest extends TestCase {public function testThisIsASampleTest() {$this->assertTrue(true);
}
} Pour exécuter tous les tests, exécutez vendor/bin/phpunit --testdox dans le répertoire racine du projet.
root@ubuntu:/chemin/vers/projet$ vendeur/bin/phpunit --testdox PHPUnit 7.5.16 par Sebastian Bergmann et contributeurs. Échantillon Ceci est un exemple de test
Pour exécuter un seul fichier de test, indiquez son chemin : vendor/bin/phpunit --testdox tests/unit/SampleTest.php
L'indicateur --testdox est facultatif, mais recommandé, car il générera des phrases descriptives sur les tests en fonction de leurs noms (comme indiqué dans la section ci-dessus), ce qui facilitera la compréhension de ce qui se passe à l'intérieur des tests.
Après l'exécution des tests, le rapport de couverture de code est généré dans le répertoire tests/build/coverage et peut être consulté en ouvrant ce chemin via un navigateur.
Aldin Kovačević , premiers travaux sur le squelette et la documentation - Aldin-SXR
Le squelette est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
Travaux en cours.
