flight php swagger
v0.6.2
Flug-Mikro-Framework gebündelt mit Swagger, PHPUnit und anderen nützlichen Dienstprogrammen. Entwickelt, um die Entwicklung von APIs anzukurbeln, die mit den oben genannten Tools erstellt wurden, indem das grundlegende Projektsetup, Testrouten und -modelle sowie die Vorlage für Komponententests einbezogen werden.
In diesem Leitfaden wird davon ausgegangen, dass Sie derzeit die folgenden Technologien in Ihrem Projekt verwenden (oder deren Verwendung planen):
PHP 7.1+
Komponist
Xdebug (erforderlich, wenn Sie PHPUnit verwenden möchten)
Stellen Sie zunächst sicher, dass Sie einen laufenden Webserver (z. B. Apache) mit PHP 7.1 oder höher installiert und konfiguriert haben.
Laden Sie mit composer das Projektgerüst herunter, installieren Sie alle erforderlichen Abhängigkeiten und führen Sie die Beispiel-Komponententests aus:
composer create-project tribeos/flight-php-swagger path/to/project
Da Flight zum Funktionieren auf das Modul mod_rewrite von Apache 2 angewiesen ist, sollten Sie es zunächst über a2enmod aktivieren und dann den Server neu starten:
sudo a2enmod rewrite
sudo systemctl restart apache2
Anschließend sollten Sie auch die Standardkonfigurationsdatei von Apache bearbeiten, da diese zunächst die Verwendung einer .htaccess Datei zum Anwenden von Rewrite-Regeln verbietet. Die Konfigurationsdatei befindet sich normalerweise unter /etc/apache2/apache2.conf . Suchen Sie darin den Block, der auf das Verzeichnis /var/www verweist, und stellen Sie sicher, dass AllowOverride auf All “ gesetzt ist und dass Require all granted aktiviert ist.
<Verzeichnis /var/www/>Optionsindizes FollowSymLinksAllowOverride AllRequire alle gewährt </Verzeichnis>
Nachdem Sie die Änderungen gespeichert haben, starten Sie den Apache-Server neu.
Falls Sie mehrere Site-Konfigurationen haben oder haben möchten, können Sie die Umschreiberegeln auch pro Site aktivieren, indem Sie die gewünschte Konfigurationsdatei in /etc/apache2/sites-available bearbeiten. Weitere Informationen finden Sie im folgenden Tutorial.
Hinweis : Bei den oben genannten Anweisungen wird davon ausgegangen, dass Sie eine Ubuntu-Distribution verwenden. Falls Sie ein anderes Betriebssystem verwenden, lesen Sie bitte das entsprechende Tutorial zur Aktivierung des Rewrite-Moduls.
Windows (WAMP/XAMPP)
CentOS
Das Projekt und seine Abhängigkeiten erfordern die Installation bestimmter PHP-Erweiterungen. Häufige Erweiterungen, die Ihnen möglicherweise fehlen, könnten einige der folgenden sein:
| Ausgabe | Lösung |
|---|---|
mbstring | sudo apt install php-mbstring |
zip und unzip bezogene Probleme | sudo apt install zip unzip php-zip |
Hinweis : Wie im vorherigen Abschnitt zu Apache 2 beziehen sich diese Anweisungen auf Ubuntu-Distributionen. Wenn Sie ein anderes Betriebssystem verwenden, verwenden Sie einen geeigneten alternativen Befehl.
Sobald die Installation abgeschlossen ist, finden Sie diese Struktur in Ihrem Projekt:
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
Überblick über die wichtigsten Projektkomponenten:
app : der Hauptanwendungsordner
models : Modelle, die für Anfragen/Antworten verwendet werden
routes : Definition von API-Routen
utils : Anwendungsdienstprogramme wie Validatoren und Logger
config : Konfigurationsdatei(en)
docs : Swagger-Dokumentationsdateien
logs : Protokollspeicher
tests : Ordner für Anwendungstests
build : Alle kompilierten Dateien, die aus Tests resultieren (Codeabdeckung usw.)
src : Quelldateien testen
vendor : Speicherort aller Bibliotheken und des Codes von Drittanbietern
autoload.php : Eine Bootstrapping-Datei, die Composer-Abhängigkeiten lädt und alle anderen Projektdateien einschließt
index.php : API-Einstiegspunkt
phpunit.xml : PHPUnit-Testkonfiguration
Die gesamte Hauptkonfiguration im Zusammenhang mit dem Projekt (und der Swagger-Dokumentation) wird in der Datei config/config.php verwaltet. Ändern/fügen Sie die Konfigurationskonstanten entsprechend Ihren Projektanforderungen hinzu.
Eine weitere wichtige Datei ist index.php , die als API-Einstiegspunkt dient. Es erfordert die Datei autoload.php , die den Code zum Laden von Composer-Abhängigkeiten sowie alle anderen erforderlichen Projektdateien enthält. Darüber hinaus wird das Flight-Framework gestartet. Die standardmäßig importierten Dateien sind alle models , routes und utils sowie die Projektkonfigurationsdatei ( config/config.php ), die Swagger-PHP-Konfigurationsdatei ( docs/swagger.php ) und die vendor/autoload.php des Composers. Ändern/fügen Sie die zu importierenden Dateien entsprechend Ihren Projektanforderungen hinzu.
Flight ist ein erweiterbares und benutzerfreundliches PHP-Framework, das die schnelle Erstellung von RESTful-Web-APIs ermöglicht. Sie können damit detaillierte und funktionale API-Endpunkte erstellen, gekoppelt mit Middleware-Funktionen und der Möglichkeit, benutzerdefinierte Methoden zu überschreiben/erstellen.
Flight::route('GET /sample/@value', function($value) {
Flight::json([ 'sample_value' => $value ]);
}); Das gesamte Routing im Projekt erfolgt über Flight. Die anfängliche Flugeinrichtung ( FlightSetup.php ) sowie alle Projektrouten werden im routes verwaltet und können an Ihre Bedürfnisse angepasst werden.
Ausführliche Nutzungsdokumentationen und Beispiele zu Flight finden Sie auf der Flight-Homepage – Bereich „Lernen“. Weitere Informationen zum Flight-Framework selbst finden Sie im GitHub-Repository.
Nachdem Sie eine Route im routes erstellt haben, können Sie mit dem Schreiben und Generieren der OpenAPI-Dokumentation für Ihre RESTful-API beginnen.
Die Dokumentation wird in DocBlocks , auch PHP-Kommentarblöcke genannt, über der entsprechenden Route geschrieben.
/** * @OAGet( * path="/sample/route", * tags={"sample"}, * summary="Eine Beispielroute.", * @OAResponse( * Response=200, * description="A Beispielantwort." * ), * security={ * {"api_key": {}} * } * )*/Sie können den Pfad, Tags, eine kurze Zusammenfassung, Parameter, Standardparameterwerte, den Anforderungstext, verfügbare Antworten, Sicherheitsauthentifizierung und zahlreiche andere Optionen für jeden RESTful-Endpunkt definieren.
Allgemeine Swagger-Konfigurationen wie Projektname, Projektautor(en), API-Server-URL, Spezifikationsordner usw. können in config/config.php im Bereich „Swager-Konfigurationskonstanten“ gefunden und konfiguriert werden.
Das Projektgerüst ist mit dem Ordner docs gekoppelt, der alle notwendigen Dateien für die Swagger-Dokumentation enthält (PHP-Setup-Dateien, HTML und CSS). Sie können auf die Dokumentation zugreifen, indem Sie über einen Browser zur Stammroute ( / ) Ihres Projekts navigieren.
Weitere Informationen zu Swagger im Allgemeinen und dem OpenAPI-Standard finden Sie auf der offiziellen Homepage von Swagger. Eine ausführliche Nutzungsdokumentation und Beispiele zur PHP-Implementierung finden Sie auf der offiziellen Homepage von swagger-php.
Das Projekt wird mit http-logger geliefert, einem HTTP-Anfrage-, Antwort- und Fehlerlogger, der (standardmäßig) jede eingehende Anfrage und die entsprechende Antwort als tabulatorgetrennte Werte (TSV) in logs/debug.log protokolliert. Detaillierte Logger-Informationen und Konfigurationsdetails finden Sie auf der GitHub-Seite.
Der Logger benötigt den Speicherort der Protokolldatei (der standardmäßig über eine Konstante in config/config.php konfiguriert wird). Um die Funktionen des Loggers voll auszunutzen, sollte außerdem der interne Fehlerbehandler von Flight deaktiviert werden (falls aktiviert, fängt er bestimmte Fehlertypen vor dem http-Logger ab).
/* Den internen Fehlerlogger von FlightPHP deaktivieren. */Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* Den Logger abrufen und verwenden */$logger = HttpLogger::get();$logger->log(); Der Logger wird über routes/FlightSetup.php eingebunden und in der Flight-Middleware-Funktion Flight::after() konfiguriert, die nach jeder Anfrage ausgeführt wird (damit sie die entsprechende Antwort abrufen kann). Sie können die Funktionen des Loggers sowie die Routen, die er überwacht, nach Ihrem Wunsch ändern.
Flight::output() Flight::output() ist eine benutzerdefinierte zugeordnete Methode, die die Funktionen von Flight::json() (JSON-Antwortausgabe) und dem benutzerdefinierten HTTP-Logger kombiniert. Jede API-Antwort, die über diese Methode gesendet wird, wird entsprechend den im Logger festgelegten Einstellungen automatisch protokolliert. Die Methode wird in routes/FlightSetup.php definiert und konfiguriert.
Dies ist nützlich, wenn Sie die Protokollierungsfunktion für Ihre Anfrage-/Antwortpaare nutzen möchten, ohne Flight-Middleware zum Abfangen zu verwenden.
Flight::output() benötigt zwei Parameter: die tatsächlich zu versendenden Daten ( erforderlich ) und den Antwortcode ( optional , standardmäßig 200).
Flight::output(['sample_message' => 'Beispielantwort.'], 301);
Flight::validate() Flight::validate() verwendet Swagger-PHP-Analysen, um zu bestimmen, ob ein übergebener Anforderungstext gemäß der erwarteten OpenAPI-Modellspezifikation gültig ist (alle erforderlichen Attribute enthält).
Alle Modelle werden als Klassen deklariert und ihre Attribute werden auf öffentlich gesetzt. Die Modelle werden in app/models definiert und folgen dieser Struktur:
/** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * description="Beispielattribut des Anforderungstexts.", * example="Beispielzeichenfolge." * erforderlich=true * ) * @ var string */public $sample_attribute;
} In diesem konkreten Beispiel wird description verwendet, um einen kurzen Überblick über die Eigenschaft des Modells zu geben, required legt fest, ob die Eigenschaft obligatorisch ist oder nicht, und example weist ihr einen Standardwert zu. Weitere Informationen zu Modellschemata finden Sie in der Swagger-PHP-Dokumentation.
Die Modellvalidatorklasse wird in utils/Validator.php deklariert und definiert und als benutzerdefinierte zugeordnete Flight-Methode routes/FlightSetup.php enthalten. Es benötigt zwei Parameter: die Klasse, anhand derer der Anfragetext validiert werden soll, und den Anfragetext selbst.
Flight::validate(SampleModel::class, Flight::request()->data->getData());
Die Methode sollte innerhalb einer API-Route aufgerufen werden, bevor weitere Methoden aufgerufen werden. Wenn das Modell gültig ist, wird die Anfrage mit der Ausführung fortgesetzt. Falls die Validierung des Modells fehlschlägt, gibt es den Antwortcode 400 Bad Request aus und bricht die Anfrage ab.
Hinweis : Flight::validate() hängt von Flight::output() ab. Wenn Sie also vorhaben, die benutzerdefinierte Ausgabemethode aus dem Projekt zu entfernen, sollten Sie die vom Validator zugeordnete Methode nach Bedarf neu schreiben.
Das Projekt ist in PHPUnit enthalten, einem Testframework für PHP, das neben dem Testen selbst auch die Generierung der Codeabdeckung ermöglicht.
Die gesamte Einrichtung zum Testen mit PHPUnit befindet sich in phpunit.xml . Für die Einrichtung stehen Ihnen mehrere Optionen zur Verfügung:
Der Speicherort der Testdateien Innerhalb des testsuites -Tags kann der Speicherort definiert werden, der nach Tests durchsucht wird. Standardmäßig ist dies tests/unit . Wenn ein Testverzeichnis definiert ist (per directory Tag), werden die Testdateien während der Testausführung in alphabetischer Reihenfolge ausgeführt. Bei Bedarf können wir die Testdateien auch per file -Tag in einer benutzerdefinierten Reihenfolge definieren.
<testsuites>
<testsuite name="sample-test-suite">
<directory suffix="Test.php">tests/src/</directory><!-- Standardmäßig werden Testdateien in alphabetischer Dateireihenfolge ausgeführt. Wenn Sie eine bestimmte Ausführungsreihenfolge festlegen möchten, definieren Sie einzelne Testdateien--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
</testsuites> Arten von Testabdeckungsberichten Nach der Ausführung der Tests können verschiedene Arten von Testberichten generiert werden. Die Protokolltypen werden im logging Tag definiert. Alle kompilierten Testdateien befinden sich standardmäßig in tests/build .
<logging><!-- Arten von Testprotokollen --><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> Von der Codeabdeckung einzuschließende/auszuschließende Dateien Sie können auch auswählen, welche Dateien in den Codeabdeckungsbericht einbezogen (oder daraus ausgeschlossen) werden sollen. Dies geschieht über das filter -Tag innerhalb des whitelist -Tags. Standardmäßig deckt das PHPUnit-Setup des Projekts Dateien im app Verzeichnis ab, mit Ausnahme von models und routes (da diese Ordner keinen Code enthalten, der effektiv auf Codeabdeckung getestet werden kann). Sie können auch Ihre benutzerdefinierten Einschluss-/Ausschlussordner und Dateien definieren.
<Filter>
<whitelist><!-- Der Name des Ordners, der für die Codeabdeckung verwendet werden soll –><directory suffix=".php">app/</directory>
<exclude><!-- Dateien/Ordner, die von der Codeabdeckung ausgeschlossen sind (PHP-Dateien ohne testbare Methoden). Bearbeiten Sie es entsprechend Ihren Projektanforderungen. --><directory suffix=".php">app/models</directory>
<directory suffix=".php">app/routes</directory>
</exclude>
</whitelist>
</filter> Alle Unit-Tests sollten standardmäßig im Verzeichnis tests/unit geschrieben werden. Testdateinamen sollten mit Test.php enden, damit sie von PHPUnit (wie in phpunit.xml definiert) erkannt werden können, z. B. SampleTest.php .
Eine Testklasse ist als Erweiterung der TestCase -Klasse definiert und kann verschiedene Testmethoden umfassen. Bei der Benennung der Tests können Sie die folgende Konvention verwenden: test + Beschreibung des Tests in Camel-Case (z. B. testThisIsASampleTest ). Dadurch kann der Testfallname während der Testausführung in einen beschreibenden Satz umgewandelt werden, was dem Entwickler einen zusätzlichen Überblick darüber gibt, was der Test tun soll.
/* tests/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest erweitert TestCase {public function testThisIsASampleTest() {$this->assertTrue(true);
}
} Um alle Tests auszuführen, führen Sie vendor/bin/phpunit --testdox im Stammverzeichnis des Projekts aus.
root@ubuntu:/path/to/project$ seller/bin/phpunit --testdox PHPUnit 7.5.16 von Sebastian Bergmann und Mitwirkenden. Probe Dies ist ein Beispieltest
Um nur eine einzelne Testdatei auszuführen, geben Sie deren Pfad an: vendor/bin/phpunit --testdox tests/unit/SampleTest.php
Das Flag --testdox ist optional, wird aber empfohlen, da es beschreibende Sätze über die Tests basierend auf ihren Namen generiert (wie im Abschnitt oben beschrieben), was es einfacher macht, zu verstehen, was in den Tests vor sich geht.
Nach der Ausführung der Tests wird der Code-Coverage-Bericht im Verzeichnis tests/build/coverage generiert und kann durch Öffnen dieses Pfads über einen Browser angezeigt werden.
Aldin Kovačević , erste Arbeiten am Skelett und Dokumentation – Aldin-SXR
Das Skelett ist unter der MIT-Lizenz lizenziert. Einzelheiten finden Sie in der LICENSE-Datei.
In Arbeit.
