Swagger/OpenAPI-Generierung für PHP

Swagger/OpenAPI-Generierung für PHP: Vollständiger Überblick über Werkzeuge

In der modernen Webentwicklung ist die Erstellung einer qualitativ hochwertigen API-Dokumentation nicht nur guter Stil, sondern eine Notwendigkeit. Swagger (jetzt bekannt als OpenAPI) ist ein Standard zur Beschreibung von RESTful-APIs, der die Automatisierung der Generierung von Dokumentation, Client-SDKs und Test-Konsolen-Schnittstellen ermöglicht. In diesem Artikel betrachten wir im Detail, wie Swagger/OpenAPI für PHP-Projekte verwendet wird, welche Bibliotheken existieren und wie man sie richtig integriert.

Was ist Swagger/OpenAPI?

Die OpenAPI Specification (OAS) ist eine Spezifikation, die den Standard zur Beschreibung von REST-APIs im JSON- oder YAML-Format definiert. Sie ermöglicht:

Automatische Generierung interaktiver Dokumentation (Swagger UI);
Erstellung von Client-Bibliotheken für verschiedene Programmiersprachen;
Überprüfung der Korrektheit von Anfragen und Antworten;
Integration in CI/CD-Pipelines.

Wichtige Bibliotheken für PHP

Für die Arbeit mit OpenAPI in PHP gibt es mehrere beliebte Bibliotheken. Betrachten wir jede davon genauer.

1. Swagger-PHP (zircote/swagger-php)

Dies ist die beliebteste und ausgereifteste Bibliothek zur Generierung von OpenAPI-Spezifikationen aus PHP-Annotationen. Sie ermöglicht die Beschreibung der API direkt im Code, was die Pflege der Dokumentation auf dem neuesten Stand vereinfacht.

Installation:

composer require zircote/swagger-php

Anwendungsbeispiel:

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="Meine API", *     version="1.0.0", *     description="Beispiel-API zur Demonstration von Swagger" * ) * @OA\\Server( *     url="https://api.example.com", *     description="Production server" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="Liste der Benutzer abrufen",     *     @OA\\Response(     *         response=200,     *         description="Erfolgreiche Antwort",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // Logik zum Abrufen der Benutzer    }

    /**     * @OA\\Schema(     *     schema="User",     *     type="object",     *     @OA\\Property(property="id", type="integer"),     *     @OA\\Property(property="name", type="string"),     *     @OA\\Property(property="email", type="string")     * )     */    public function userSchema()    {        // Leere Methode zur Beschreibung des Schemas    }}

// Generierung der Spezifikation$openapi = \\OpenApi\\Generator::scan(['/path/to/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

Diese Bibliothek ermöglicht nicht nur die Beschreibung der API, sondern auch die automatische Generierung von Servercode basierend auf der OpenAPI-Spezifikation. Sie ist besonders nützlich bei der Anwendung des Design-First-Entwicklungsansatzes.

Installation:

composer require thecodingmachine/openapi-server

Beispiel zur Server-Generierung:

<?phpuse TheCodingMachine\\OpenAPI\\Server\\Builder;

// Laden der Spezifikation$spec = json_decode(file_get_contents('openapi.json'), true);

// Erstellung des Servers$builder = new Builder();$server = $builder->build($spec, 'App\\\\Controllers\\\\');

// Verarbeitung der Anfrage$response = $server->handle($request);?>