Swagger/OpenAPI-Generierung für PHP: Die besten Tools und Bibliotheken

Swagger/OpenAPI-Generierung für PHP: Automatisierung der API-Dokumentation

\n\n

Swagger (jetzt OpenAPI) ist ein Standard zur Beschreibung von RESTful-APIs, der es Entwicklern, Clients und automatisierten Tools ermöglicht, die Fähigkeiten eines Dienstes ohne Zugriff auf den Quellcode zu verstehen. Für PHP-Entwickler ist die Bibliothek zircote/swagger-php (früher bekannt als swagger-php) das wichtigste Werkzeug, das automatisch eine OpenAPI-Spezifikation aus Annotationen im Code generiert.

\n\n

Was ist zircote/swagger-php?

\n\n

Dies ist die Hauptbibliothek zur Generierung von OpenAPI-Spezifikationen in PHP. Sie analysiert PHPDoc-Annotationen in Controllern, Modellen und Routen und erstellt eine JSON/YAML-Datei, die verwendet werden kann für:

\n\n

\n
• Automatische Generierung von Dokumentation (Swagger UI, ReDoc)
\n
• Generierung von Client-Bibliotheken für verschiedene Sprachen
\n
• API-Tests (Postman, Insomnia)
\n
• Validierung von Anfragen und Antworten
\n

\n\n

Installation und Konfiguration

\n\n

Installation über Composer:

\n\n

composer require zircote/swagger-php

\n\n

Die minimale Konfiguration für Laravel (oder jedes andere Framework) umfasst die Erstellung von Annotationen im Controller. Beispiel eines einfachen Controllers mit OpenAPI-Annotationen:

\n\n

<?php\n\nnamespace App\\Http\\Controllers\\Api;\n\nuse OpenApi\\Annotations as OA;\n\n/**\n * @OA\\Info(title="My API", version="1.0.0")\n * @OA\\Server(url="https://api.example.com")\n */\nclass UserController extends Controller\n{\n    /**\n     * @OA\\Get(\n     *     path="/api/users/{id}",\n     *     summary="Benutzer nach ID abrufen",\n     *     @OA\\Parameter(\n     *         name="id",\n     *         in="path",\n     *         required=true,\n     *         @OA\\Schema(type="integer")\n     *     ),\n     *     @OA\\Response(\n     *         response=200,\n     *         description="Erfolgreiche Antwort",\n     *         @OA\\JsonContent(ref="#/components/schemas/User")\n     *     ),\n     *     @OA\\Response(response=404, description="Benutzer nicht gefunden")\n     * )\n     */\n    public function show($id)\n    {\n        // Logik\n    }\n}

\n\n

Generierung der Spezifikation

\n\n

Um die OpenAPI-Datei zu erstellen, führen Sie den Befehl aus:

\n\n

vendor/bin/openapi src -o public/openapi.yaml

\n\n

Oder verwenden Sie PHP-Code:

\n\n

<?php\n\nuse OpenApi\\Generator;\n\n$openapi = Generator::scan(['/path/to/project/src']);\nfile_put_contents('public/openapi.json', $openapi->toJson());

\n\n

Erweiterte Funktionen

\n\n

Die Bibliothek unterstützt:

\n\n

\n
• Verschachtelte Schemata — automatische Erstellung von Modellen aus Annotationen
\n
• Gruppierung von Endpunkten über @OA\\Tag
\n
• Sicherheit — @OA\\SecurityScheme für JWT, OAuth2
\n
• Beispielanfragen — @OA\\RequestBody mit Beispielen
\n

\n\n

Beispiel eines Modells mit Annotationen:

\n\n

<?php\n\n/**\n * @OA\\Schema(\n *     schema="User",\n *     required={"id", "email"},\n *     @OA\\Property(property="id", type="integer", format="int64"),\n *     @OA\\Property(property="email", type="string", format="email"),\n *     @OA\\Property(property="name", type="string"),\n *     @OA\\Property(property="created_at", type="string", format="date-time")\n * )\n */\nclass User\n{\n    // Eigenschaften\n}

\n\n

Integration mit Frameworks

\n\n

Für Laravel gibt es das Paket darkaonline/l5-swagger, das Folgendes hinzufügt:

\n\n

\n
• Automatische Generierung bei jeder Anfrage
\n
• Integrierte Swagger UI
\n
• Konfiguration über eine config-Datei
\n

\n\n

Installation:

\n\n

composer require darkaonline/l5-swagger\nphp artisan vendor:publish --provider="L5Swagger\\L5SwaggerServiceProvider"

\n\n

Für Symfony verwenden Sie nelmio/api-doc-bundle.

\n\n

Vergleich