Schritt 1: Laravel-Anwendung einrichten
Falls Sie noch keine Laravel-Anwendung haben, können Sie eine neue erstellen:
Navigieren Sie in das erstellte Verzeichnis:
composer create-project --prefer-dist laravel/laravel swagger-examplecd swagger-exampleSchritt 2: Swagger-Paket installieren
composer require "darkaonline/l5-swagger"Schritt 3: Konfiguration veröffentlichen
Veröffentlichen Sie die Konfigurationsdatei von L5-Swagger:
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"Schritt 4: Swagger-Konfiguration anpassen
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:
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:
php artisan l5-swagger:generateSchritt 7: Swagger UI aufrufen
Starten Sie den Laravel-Entwicklungsserver:
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.
Kommentare 0
Noch keine Kommentare. Seien Sie der Erste!