Swagger-PHP für PHP: Komplette Anleitung mit Beispielen

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

Swagger-PHP ist eine leistungsstarke Bibliothek für die Programmiersprache PHP, die automatisch eine OpenAPI (ehemals Swagger) Spezifikation Ihrer REST-API auf Basis von Annotationen im Code generiert. Anstatt riesige YAML- oder JSON-Dateien manuell zu schreiben, die alle Endpunkte, Parameter, Datenmodelle und Antworten beschreiben, fügen Sie einfach spezielle Kommentare (Annotationen) direkt in Ihre Controller, Modelle und Routen der PHP-Anwendung ein. Die Bibliothek analysiert diese Annotationen und erstellt eine vollständige, gültige OpenAPI-Spezifikation, die im JSON- oder YAML-Format exportiert werden kann.

Warum ist das notwendig? In der modernen Webentwicklung ist die API die zentrale Schnittstelle für die Kommunikation zwischen Frontend, mobilen Apps und Drittanbieterdiensten. Die Dokumentation aktuell zu halten, ist ein ständiger Schmerzpunkt. Swagger-PHP löst dieses Problem, indem es die Dokumentation direkt mit dem Quellcode verknüpft. Wenn Sie die Logik eines Endpunkts ändern, ändern Sie auch die dazugehörige Annotation. Die Dokumentation entspricht immer dem tatsächlichen Verhalten der API. Das spart Stunden an Arbeit, reduziert Integrationsfehler und macht Ihr Projekt für neue Entwickler transparent.

Darüber hinaus kann die generierte OpenAPI-Spezifikation mit Dutzenden von Tools verwendet werden: Swagger UI (interaktive Dokumentation, in der Sie Anfragen direkt im Browser testen können), Client-SDK-Generatoren für JavaScript, Python, Java und andere Sprachen, Test- und Validierungstools (z. B. Postman oder Insomnia) sowie zur automatischen Generierung von Mock-Servern. Swagger-PHP ist der De-facto-Standard für die Dokumentation von PHP-APIs.

2. Installation

Die Installation erfolgt über Composer, den Standard-Paketmanager für PHP. Führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus:

composer require zircote/swagger-php

Nach der Installation erscheint im Projekt das Verzeichnis vendor/zircote/swagger-php. Die Bibliothek benötigt PHP Version 8.0 oder höher (zur Unterstützung moderner PHP 8 Attribute). Wenn Sie eine ältere PHP-Version verwenden, benötigen Sie die Bibliotheksversion 3.x, aber es wird dringend empfohlen, auf PHP 8+ zu wechseln und die neueste Swagger-PHP-Version (4.x) zu verwenden.

3. Schnellstart – Minimales funktionierendes Beispiel

Erstellen wir einen einfachen Controller mit einem Endpunkt und generieren eine OpenAPI-Spezifikation dafür.

Schritt 1: Erstellen Sie die Datei src/Controllers/UserController.php

<?php

namespace App\Controllers;

use OpenApi\Attributes as OA;

class UserController
{
    #[OA\Get(
        path: '/api/users/{id}',
        summary: 'Benutzer nach ID abrufen',
        tags: ['Users']
    )]
    #[OA\Parameter(
        name: 'id',
        in: 'path',
        required: true,
        schema: new OA\Schema(type: 'integer')
    )]
    #[OA\Response(
        response: 200,
        description: 'Erfolgreiche Antwort',
        content: new OA\JsonContent(
            properties: [
                new OA\Property(property: 'id', type: 'integer'),
                new OA\Property(property: 'name', type: 'string'),
                new OA\Property(property: 'email', type: 'string')
            ]
        )
    )]
    public function getUser(int $id): array
    {
        // Hier sollte die Logik zum Abrufen des Benutzers aus der DB stehen
        return [
            'id' => $id,
            'name' => 'Max Mustermann',
            'email' => 'max@example.com'
        ];
    }
}

Schritt 2: Erstellen Sie ein Skript zur Generierung der Spezifikation generate-docs.php

<?php

require_once __DIR__ . '/vendor/autoload.php';

use OpenApi\Generator;

// Geben Sie das Verzeichnis an, in dem sich Ihre Controller mit Annotationen befinden
$openapi = Generator::scan(['src/Controllers']);

// Speichern