Automatische Generierung von API-Dokumentation in Laravel

Das erstellen von Schnittstellen Dokumentationen ist aufwendig, fehleranfällig und benötigt viel Zeit. Mit dem Composer Paket Scramble kann automatisch API-Dokumentationen erstellt werden und diese auf einer Unterseite präsentiert werden.

Die Dokumentation wird im OpenAPI 3.1.0 Format erstellt und mit Hilfe von Spotlight Elements präsentiert.

Auf der Zieldomain kann nach erfolgreicher Installation die Dokumentation unter domain.tld/docs/api aufgerufen werden. Die Dokumentation ist, solange nicht anders konfiguriert, ausschließlich im Entwicklungsmodus erreichbar. Sobald in der .env die APP_ENV angepasst wird ist sie nicht mehr erreichbar.

Installation

Das Paket scramble wird per Composer installiert:

composer require dedoc/scramble

Ebenfalls muss dbal installiert werden, damit Modell Attribute und Relations angezeigt werden:

composer require doctrine/dbal

Anschließend kann eine Konfigurationsdatei veröffentlicht werden, welche Einstellungen zur Sicherheit beinhaltet. Die Standardeinstellungen reichen allerdings vollkommen aus.

php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"

Verwendung

Damit Informationen automatisch angezeigt werden muss der Code sauber gepflegt sein. Vor die Funktion im Controller muss ein Block platziert werden, der die Funktion benennt und beschreibt:

Im Frontend wird uns diese Information dann so angezeigt:

Wird das Request mit validate(), bzw. Validator geprüft, werden die entsprechenden Felder auch gekennzeichnet. Welche Schreibweise der Methode verwendet wird ist egal:

Die Antwort wird ebenfalls automatisch gefüllt. Sollte es sich dabei um ein Modell handeln so wird dieses komplett ausgegeben. Aktuell funktioniert dies nur mit einer JSONResource, das wird sich allerdings im nächsten Release laut dem Entwickler ändern und Modelle sollen auch direkt ausgegeben werden können, ohne dass man neue Resourcen für alle Modelle erstellen muss.

Des Weiteren werden alle möglichen Responses und deren Antworten und deren möglicher Inhalt angezeigt. Im nächsten Release wird es außerdem möglich sein, die Responses individuell zu beschriften und zu beschreiben.

Das Projekt wurde erst vor wenigen Tagen veröffentlicht, aber der Entwickler ist schnell bei der Umsetzung von Feature Requests und freut sich über Feedback. Die Github Seite des Projektes können Sie hier finden, die offizielle Dokumentation hier.

Sollten Sie noch Fragen haben oder eine Beratung wünschen, können Sie gerne mit uns Kontakt aufnehmen oder unsere Webseite besuchen.

Gerne können Sie hier auch andere Artikel zum Thema Laravel anschauen.