Swagger-PHP ist immer das Erste, was einem in den Sinn kommt, wenn man an die Generierung einer Swagger-Spec für ein PHP-Projekt denkt. Was ist also Swagger-PHP? Wie erstellt man Specs mit Swagger-php? In diesem Artikel werden wir diese Fragen beantworten und Ihnen die Details vorstellen.

Was ist Swagger-PHP

swagger-PHP ist ein Tool zur Generierung von API-Dokumentation mit Swagger (jetzt bekannt als die OpenAPI-Spezifikation) in PHP. swagger-php hilft PHP-Entwicklern, API-Dokumentation basierend auf der Swagger (OpenAPI)-Spezifikation zu erstellen. Dieses Tool kann Swagger (OpenAPI)-Spezifikationen aus PHP-Code generieren. Es ermöglicht Entwicklern, API-Endpunkte, Anfragen und Antworten im Code zu definieren und automatisch eine Swagger (OpenAPI)-Spezifikation zu generieren.

Funktionen von Swagger-PHP

Swagger-PHP ist ein leistungsstarkes Tool zur Generierung von Spezifikationen für OpenAPI-Versionen 3.0 und 3.1. Es ist auch in der Lage, APIs mit PHP-Quellcode aufzuzeichnen. Das von Swagger-php verwendete Annotationsattribut kann entweder Doc-Blöcke oder PHP 8.1 sein, was es hochflexibel und vielseitig macht.

Egal, ob Sie mit Doc-Blöcken oder der neuesten PHP-Version arbeiten, Swagger-php kann Ihnen helfen, Ihren API-Entwicklungsprozess zu rationalisieren und insgesamt effizienter zu gestalten.

Wie man in Swagger-PHP installiert und einrichtet

Um mit der Verwendung von Swagger-PHP zu beginnen, müssen Sie es zuerst installieren. Swagger-PHP kann mit Composer, einem Dependency Manager für PHP, installiert werden.

Um Swagger-PHP zu installieren, führen Sie den folgenden Befehl in Ihrem Terminal aus:

composer require zircote/swagger-php

Nach der Installation können Sie mit Swagger-PHP beginnen, um Swagger-Dokumentation für Ihre API zu generieren.

Als Nächstes müssen Sie Swagger-PHP einrichten, indem Sie eine neue Swagger-Instanz erstellen und sie mit Ihren API-Informationen konfigurieren. Hier ist ein Beispiel, wie man Swagger-PHP einrichtet:

require_once('vendor/autoload.php');

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     basePath="/api",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="My API",
 *         description="API documentation for My API",
 *         @SWG\Contact(name="My Company"),
 *         @SWG\License(name="MIT")
 *     )
 * )
 */

In diesem Beispiel haben wir eine neue Swagger-Instanz erstellt und sie mit unseren API-Informationen konfiguriert, wie z. B. dem Basispfad, den Schemata und den API-Informationen (Version, Titel, Beschreibung, Kontakt und Lizenz).

Sobald Sie Swagger-PHP eingerichtet haben, können Sie damit beginnen, Swagger-Annotationen zu Ihrem API-Code hinzuzufügen, um Swagger-Dokumentation zu generieren. Wir werden dies im nächsten Abschnitt ausführlicher behandeln.

Erstellen von Swagger-Dokumentation mit Swagger-PHP

Swagger-PHP ist eine PHP-Bibliothek zur Generierung von Swagger-Dokumenten. In diesem Abschnitt erfahren wir, wie man mit Swagger-PHP Swagger-Dokumentation erstellt.

Schritt 1. Definieren von API-Informationen

Zuerst müssen wir die Informationen der API definieren. Dies beinhaltet den Titel, die Beschreibung, die Version usw. der API. Das Folgende ist ein Beispiel:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ]);

Schritt 2. Definieren der API-Endpunkte

Als Nächstes müssen wir die Endpunkte der API definieren. Dies beinhaltet die HTTP-Methoden, Pfade, Parameter und Antworten für jeden Endpunkt. Das Folgende ist ein Beispiel:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ]);

Schritt 3. Definieren des Datenmodells

Schließlich müssen wir die Datenmodelle definieren. Dies beinhaltet die Attribute und Typen jedes Modells. Das Folgende ist ein Beispiel:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ])
    ->definitions([
        'User' => [
            'type' => 'object',
            'properties' => [
                'id' => [
                    'type' => 'integer',
                    'format' => 'int64'
                ],
                'name' => [
                    'type' => 'string'
                ],
                'email' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]);

Schritt 4. Exportieren von Swagger-Dokumenten

Schließlich können wir die Swagger-Dokumentation mit dem folgenden Code ausgeben:

header('Content-Type: application/json');
echo $swagger->toJson();

Dadurch wird ein Swagger-Dokument im JSON-Format ausgegeben, das zur Generierung von API-Dokumentation verwendet werden kann.

Integrieren von Swagger UI mit Swagger-PHP

Um die Vorteile der Swagger-Dokumentation voll auszuschöpfen, ist es wichtig, eine benutzerfreundliche Oberfläche zu haben, um die Dokumentation anzuzeigen und mit ihr zu interagieren. Hier kommt Swagger-ui ins Spiel. Swagger-UI ist eine webbasierte Oberfläche, die eine interaktive Erfahrung zum Anzeigen und Testen der Swagger-Dokumentation bietet.

Die Integration von Swagger-UI mit Swagger-PHP ist ein unkomplizierter Prozess. Laden Sie zuerst die neueste Version von Swagger-UI aus dem offiziellen GitHub-Repository herunter. Extrahieren Sie dann den Inhalt des heruntergeladenen Archivs in ein Verzeichnis auf Ihrem Webserver.

Erstellen Sie als Nächstes eine neue PHP-Datei, die als Einstiegspunkt für Swagger-UI dient. Fügen Sie in dieser Datei die erforderlichen CSS- und JavaScript-Dateien für Swagger-UI sowie die Swagger-ui-JavaScript-Bibliothek selbst ein. Sie müssen auch die von Swagger-PHP generierte JSON-Datei einfügen, die Ihre API-Dokumentation enthält.

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="path/to/swagger-ui.css">
  <script type="text/javascript" src="path/to/swagger-ui-bundle.js"></script>
  <script type="text/javascript" src="path/to/swagger-ui-standalone-preset.js"></script>
</head>
<body>
  <div id="swagger-ui"></div>
  <script type="text/javascript">
    window.onload = function() {
      // Build a system
      const ui = SwaggerUIBundle({
        url: "path/to/swagger-json.php",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    }
  </script>
</body>
</html>

Ersetzen Sie im obigen Beispiel die Platzhalter path/to durch die tatsächlichen Pfade zu den Swagger-UI-CSS- und JavaScript-Dateien sowie der von Swagger-PHP generierten JSON-Datei.

Sobald Sie diese Datei erstellt haben, können Sie auf Swagger-UI zugreifen, indem Sie in Ihrem Webbrowser zu deren URL navigieren. Sie sollten eine voll funktionsfähige Swagger-ui-Oberfläche sehen, die Ihre API-Dokumentation anzeigt und Ihnen die Interaktion damit ermöglicht.

Zusammenfassend lässt sich sagen, dass die Integration von Swagger-UI mit Swagger-PHP ein einfacher Prozess ist, der die Benutzerfreundlichkeit Ihrer API-Dokumentation erheblich verbessert. Wenn Sie die oben beschriebenen Schritte befolgen, können Sie ganz einfach eine benutzerfreundliche Oberfläche für Ihre API-Dokumentation erstellen, die es Entwicklern erleichtert, Ihre API zu verstehen und zu verwenden.

API-Spezifikationen teilen

Nachdem ich die Swagger-Spezifikation generiert habe, teile ich sie oft mit meinen Teammitgliedern. In diesen Fällen teilen wir oft in Swagger JSON- oder OpenAPI YAML-Formaten, aber das scheint etwas veraltet zu sein.

Hier ist Apidog das perfekte API-Management-Tool, das sofort hochgradig lesbare API-Spezifikationen basierend auf Swagger JSON- oder YAML-Daten generiert. Sie können diese API-Spezifikation auch einfach mit der API-Sharing-Funktion teilen.

Apidog bietet auch verschiedene Funktionen als Tool für das API-Lifecycle-Management.

API-Design und Spezifikationsgenerierung: Apidog ist das am einfachsten zu verwendende API-Design-Tool, mit dem Sie APIs intuitiv ohne Code entwerfen und bequem OpenAPI- und Swagger-Spezifikationen generieren können.

API-Management und Unit-Tests: Apidog macht Unit-Tests sehr einfach, da Sie Ihre API effizient verwalten, API-Anfragen senden und Antworten validieren können.

API-Testautomatisierung: Apidog unterstützt auch automatisierte Tests und ist bereit für CI/CD. Durch die Verwendung dieser Funktion zum Festlegen der Anzahl der Threads usw. können Sie problemlos API-Lasttests und API-Testautomatisierung implementieren.

Fazit

Zusammenfassend lässt sich sagen, dass Swagger-PHP ein leistungsstarkes Tool zur Generierung von Swagger-Dokumentation für PHP-basierte APIs ist. Es ermöglicht Entwicklern, ihre APIs einfach zu dokumentieren und für andere Entwickler zugänglich zu machen. Darüber hinaus bietet die Integration von Swagger-UI mit Swagger-php eine benutzerfreundliche Oberfläche zum Erkunden und Testen von APIs.

Hier sind einige Ressourcen für weiteres Lernen über Swagger-PHP:

Offizielle Dokumentation: https://zircote.github.io/swagger-php/
GitHub-Repository: https://github.com/zircote/swagger-php
Swagger-ui: https://swagger.io/tools/swagger-ui/