Swagger UI und die API-Dokumentation erkunden

API Platform generiert AUTOMATISCH eine VOLLSTÄNDIGE, interaktive API-Dokumentation – kein separates Tool, kein manuelles Pflegen von Dokumentationsdateien nötig.

Die Swagger UI öffnen

open https://localhost/api/docs
# oder einfach im Browser aufrufen

JEDER Endpunkt, den wir bisher gebaut haben (/api/begruessung aus Kapitel 5), erscheint hier AUTOMATISCH – inklusive Beschreibung, erwarteten Parametern und Beispiel-Antworten.

Einen Endpunkt DIREKT in der Swagger UI testen

Klicken Sie auf einen Endpunkt, dann auf "Try it out" – die Swagger UI führt den TATSÄCHLICHEN HTTP-Aufruf aus, GENAU wie curl, aber ohne Terminal. Nützlich für schnelle, EXPLORATIVE Tests, während Sie an einer neuen Resource arbeiten.

Die rohe OpenAPI-Spezifikation

curl -k https://localhost/api/docs.json

Die Swagger UI ist letztlich nur eine VISUELLE Darstellung dieser JSON-Spezifikation – Kapitel 80 nutzt GENAU DIESE Datei, um automatisch TypeScript-Typen für unser React-Frontend zu generieren, statt sie manuell zu pflegen.

Zwei Dokumentations-Formate: Hydra und OpenAPI

Format	Zweck
OpenAPI (Swagger UI)	Der branchenübliche Standard für REST-APIs – von den MEISTEN Tools/Bibliotheken verstanden, GENAU das Format aus diesem Kapitel.
Hydra	Ein zusätzliches, semantisches Format (Teil von JSON-LD), das "selbstbeschreibende" APIs ermöglicht – für unser React-Frontend weniger relevant, aber Teil von API Platforms Standard-Ausgabe.

Eigene Beschreibungen ergänzen

#[ApiResource(
    description: 'Verwaltet Projekte im Aufgaben-Manager.',
    operations: [
        new Get(description: 'Ruft ein einzelnes Projekt anhand seiner ID ab.'),
    ],
)]
class Project
{
    // ...
}

description auf Resource- UND Operation-Ebene erscheint DIREKT in der Swagger UI – ein kleiner Aufwand, der spätere Zusammenarbeit (z. B. mit dem React-Team, das die API konsumiert, OHNE Ihren PHP-Code zu lesen) deutlich erleichtert.

Tipp: Faustregel: Beschreiben Sie ZUMINDEST Resources und Operationen, deren Verhalten NICHT sofort aus dem Namen ersichtlich ist – ein GET /projects/{id} braucht keine Erklärung, ein Custom-Endpunkt wie POST /tasks/{id}/complete (Kapitel 61) sehr wohl.