Swagger-PHP für PHP: Vollständige Anleitung mit Beispielen

Was ist Swagger-PHP und warum wird es benötigt?

Swagger-PHP ist eine leistungsstarke PHP-Bibliothek zur automatischen Generierung von REST-API-Dokumentation im OpenAPI-Format (früher bekannt als Swagger). Anstatt die Dokumentation manuell in YAML oder JSON zu schreiben, beschreiben Sie die API direkt im Code mit PHPDoc-Annotationen. Die Bibliothek analysiert diese Annotationen und generiert eine vollständige OpenAPI-Spezifikation, die mit Swagger UI, ReDoc oder anderen Tools visualisiert werden kann.

Warum ist das sinnvoll?

• Automatisierung: Die Dokumentation ist immer synchron mit dem Code. Ändern Sie einen Endpunkt – aktualisieren Sie die Annotation, und die Dokumentation ist fertig.
• Standardisierung: OpenAPI ist der Industriestandard zur Beschreibung von REST-APIs, der von Hunderten von Tools unterstützt wird.
• Komfort für das Frontend: Entwickler von Client-Anwendungen können die Spezifikation in Postman, Insomnia importieren oder Client-Code generieren.
• Testen: Die Spezifikation kann für automatisierte API-Tests verwendet werden.
• Interaktive Dokumentation: Swagger UI ermöglicht das Testen von Endpunkten direkt im Browser.

Installation von Swagger-PHP

Die Installation erfolgt über Composer – den Standard-Paketmanager für PHP. Öffnen Sie ein Terminal im Stammverzeichnis Ihres Projekts und führen Sie folgenden Befehl aus:

composer require zircote/swagger-php

Wenn Sie Laravel, Symfony oder ein anderes Framework verwenden, unterscheidet sich die Installation nicht. Nach der Installation finden Sie im Projekt den Ordner vendor/zircote/swagger-php.

Zusätzlich (optional): Zur Visualisierung der Dokumentation benötigen Sie Swagger UI. Sie können es über npm installieren:

npm install swagger-ui-dist

Oder laden Sie einfach ein fertiges Build-Paket von der offiziellen Swagger-Website herunter.

Schnellstart mit Codebeispiel

Erstellen wir eine einfache API zur Verwaltung einer Aufgabenliste (Todo-Liste) und generieren dafür die Dokumentation.

Schritt 1: Erstellen Sie die Datei index.php mit Ihrer API:

<?php
/**
 * @OA\Info(
 *     title="Todo API",
 *     version="1.0.0",
 *     description="Einfache API zur Aufgabenverwaltung"
 * )
 * @OA\Server(
 *     url="http://localhost:8000",
 *     description="Lokaler Server"
 * )
 */

use OpenApi\Annotations as OA;

/**
 * @OA\Get(
 *     path="/tasks",
 *     summary="Alle Aufgaben abrufen",
 *     @OA\Response(
 *         response=200,
 *         description="Erfolgreiche Antwort",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Task")
 *         )
 *     )
 * )
 */
function getTasks() {
    $tasks = [
        ['id' => 1, 'title' => 'Milch kaufen', 'completed' => false],
        ['id' => 2, 'title' => 'Artikel schreiben', 'completed' => true]
    ];
    header('Content-Type: application/json');
    echo json_encode($tasks);
}

/**
 * @OA\Post(
 *     path="/tasks",
 *     summary="Neue Aufgabe erstellen",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/TaskInput")
 *     ),
 *     @OA\Response(
 *         response=201,
 *         description="Aufgabe erstellt",
 *         @OA\JsonContent(ref="#/components/schemas/Task")
 *     )
 * )
 */
function createTask() {
    // Logik zum Erstellen einer Aufgabe
    echo json_encode(['id' => 3, 'title' => 'Neue Aufgabe', 'completed' => false]);
}

/**
 * @OA\Schema(
 *     schema="Task",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 * @OA\Schema(
 *     schema="TaskInput",
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 */

// Einfaches Routing
$uri = $_SERVER['REQUEST_URI'];
$method = $_SERVER['REQ