Tutorial: Swagger-Benutzeroberfläche ganz einfach in Ihre Laravel-App integrieren

Schritt 1: Laravel-Anwendung einrichten

Falls Sie noch keine Laravel-Anwendung haben, können Sie eine neue erstellen:

Navigieren Sie in das erstellte Verzeichnis:

shell

composer create-project --prefer-dist laravel/laravel swagger-example

php

cd swagger-example

Schritt 2: Swagger-Paket installieren

Es gibt verschiedene Pakete zur Integration von Swagger in Laravel. Eines der beliebtesten ist DarkaOnLine/L5-Swagger. Installieren Sie dieses Paket über Composer:

shell

composer require "darkaonline/l5-swagger"

Schritt 3: Konfiguration veröffentlichen

Veröffentlichen Sie die Konfigurationsdatei von L5-Swagger:

shell

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

Dies erstellt eine Konfigurationsdatei unter config/l5-swagger.php.

Schritt 4: Swagger-Konfiguration anpassen

Öffnen Sie die Datei config/l5-swagger.php und nehmen Sie die notwendigen Anpassungen vor. Die Standardkonfiguration funktioniert in den meisten Fällen gut, aber Sie können sie nach Bedarf anpassen.

php

return [
    'default' => 'default',
    'documentations' => [
        'default' => [
            'api' => [
                'title' => 'Swagger UI',
            ],
            'routes' => [
                'api' => 'api/documentation',
            ],
            'paths' => [
                'docs' => storage_path('api-docs'),
                'docs_json' => 'api-docs.json',
                'docs_yaml' => 'api-docs.yaml',
                'annotations' => [
                    base_path('app'),
                ],
            ],
        ],
    ],
];

Schritt 5: OpenAPI-Anmerkungen hinzufügen

Um Ihre API-Routen zu dokumentieren, müssen Sie OpenAPI-Anmerkungen zu Ihren Controller-Methoden hinzufügen. Hier ein Beispiel für einen Controller:

blade

namespace App\Http\Controllers;

use Illuminate\Http\Request;

/**
 * @OA\Info(title="API Dokumentation", version="1.0")
 */
class ApiController extends Controller
{
    /**
     * @OA\Get(
     *     path="/api/hello",
     *     summary="Sagt Hallo",
     *     @OA\Response(
     *         response=200,
     *         description="Erfolgreiche Antwort"
     *     )
     * )
     */
    public function hello()
    {
        return response()->json(['message' => 'Hallo, Welt!']);
    }
}

Schritt 6: Swagger-Dokumentation generieren

Erstellen Sie die Swagger-Dokumentation, indem Sie den folgenden Artisan-Befehl ausführen:

shell

php artisan l5-swagger:generate

Schritt 7: Swagger UI aufrufen

Starten Sie den Laravel-Entwicklungsserver:

shell

php artisan serve

Besuchen Sie http://127.0.0.1:8000/api/documentation in Ihrem Webbrowser. Sie sollten die Swagger UI sehen, die Ihre API-Dokumentation anzeigt.

Tipps zur Verwendung von Swagger in Laravel

2 Tips und 2 Infos zum Schluss..

Mit diesen Schritten und Tipps sollten Sie in der Lage sein, Swagger erfolgreich in Ihre Laravel-Anwendung zu integrieren und eine benutzerfreundliche API-Dokumentation bereitzustellen. Viel Erfolg beim Entwickeln!

Tipp

Automatisierung: Automatisieren Sie die Generierung der Swagger-Dokumentation, indem Sie den Befehl l5-swagger:generate in Ihr Deployment-Skript oder CI/CD-Pipeline einfügen.

Detailierte Dokumentation: Nutzen Sie die vielfältigen Annotationen von OpenAPI, um Ihre API detailliert zu dokumentieren, einschließlich Parameter, Rückgabewerte und Fehlercodes.

Info

Sicherheit: Dokumentieren Sie Ihre API-Sicherheitsmechanismen, wie z.B. OAuth oder JWT, um Benutzern zu zeigen, wie sie sich authentifizieren können.

Benutzerfreundlichkeit: Verwenden Sie Beispiele und Beschreibungen in Ihren API-Methoden, um die Benutzerfreundlichkeit Ihrer Dokumentation zu erhöhen.