Laravel-Entwicklung: Wie verwende ich Laravel Swagger, um API-Dokumentation zu generieren?

Laravel-Entwicklung: Wie verwende ich Laravel Swagger, um API-Dokumentation zu generieren?

Die Arbeit mit der API-Dokumentation ist bei der Entwicklung von Webanwendungen oft eine mühsame, aber wesentliche Aufgabe. Verwenden Sie Swagger, um API-Dokumentation automatisch zu generieren und zu visualisieren. In der Laravel-Entwicklung können wir das Laravel Swagger-Erweiterungspaket verwenden, um auf einfache Weise Swagger-API-Dokumentation zu generieren. In diesem Artikel erfahren Sie, wie Sie Laravel Swagger mit Laravel verwenden.

1. Installieren Sie Laravel Swagger.

Verwenden Sie Composer, um das Laravel Swagger-Erweiterungspaket zu installieren: . Verwenden Sie den folgenden Befehl, um die Veröffentlichung abzuschließen:

composer require darkaonline/l5-swagger

Nachdem Sie den Veröffentlichungsbefehl ausgeführt haben, sehen Sie das Verzeichnis swagger-ui im Verzeichnis public/vendor Swagger UI alle Ressourcen.
2. Fügen Sie als Nächstes die folgende Zeile zur Laravel-Konfigurationsdatei config/app.php hinzu:

php artisan vendor:publish --provider "L5SwaggerL5SwaggerServiceProvider"

Swagger-Annotation hinzufügen

public/vendor 目录下看到 swagger-ui 目录，这个目录中包含了 Swagger UI 的所有资源。

接下来，在 Laravel 的配置文件 config/app.php 中添加以下行：

'providers' => [
    ...
    L5SwaggerL5SwaggerServiceProvider::class,
],

'aliases' => [
    ...
    'Swagger' => L5SwaggerFacadesL5Swagger::class,
],

3. 添加 Swagger 注释

为了告诉 Laravel Swagger 没有推断的 API 格式，我们需要在代码中添加 Swagger 注释。这些注释可以让 Laravel Swagger 自动解析您的 API，并生成对应的文档。

/**
 * @OAGet(
 *      path="/users",
 *      operationId="getUsersList",
 *      tags={"Users"},
 *      summary="Get list of registered users",
 *      description="Returns list of users",
 *      @OAResponse(response="200", description="successful operation"),
 *      @OAResponse(response=401, description="Unauthorized"),
 *      @OAResponse(response=403, description="Forbidden"),
 *      @OAResponse(response=404, description="Not Found"),
 *      @OAResponse(response=500, description="Internal Server Error")
 *     )
 */

在上面的示例中，我们使用 @OAGet 注释表示这是一个 GET 请求。path 注释定义 API 的路径。tags 和 summary 注释用于在 Swagger 文档中显示摘要和标签。最后，@OAResponse 注释示例了可能的响应状态。

4. 在 Laravel 中查看 Swagger 文档

在完成所有先前的步骤之后，我们可以使用以下 URL 来查看 Laravel Swagger 文档：

http://your-app.dev/api/documentation

（请注意，如果您使用的是 Laravel 5.4 或以上版本，则无需定义 .dev，请改为使用 .testUm Laravel mitzuteilen, dass Swagger keine Schlussfolgerungen zieht Im API-Format müssen wir Swagger-Anmerkungen in den Code einfügen. Diese Annotationen ermöglichen es Laravel Swagger, Ihre API automatisch zu analysieren und entsprechende Dokumentation zu generieren.

rrreee

Im obigen Beispiel haben wir die Annotation @OAGet verwendet, um anzugeben, dass es sich um eine GET-Anfrage handelt. Die Annotation path definiert den Pfad zur API. Die Annotationen tags und summary werden zum Anzeigen von Zusammenfassungen und Tags in Swagger-Dokumenten verwendet. Schließlich veranschaulicht die Annotation @OAResponse mögliche Antwortzustände.

Swagger-Dokumentation in Laravel anzeigen

Nach Abschluss aller vorherigen Schritte können wir die folgende URL verwenden, um die Laravel Swagger-Dokumentation anzuzeigen:

rrreee

(Bitte beachten Sie, dass Sie bei Verwendung von For Laravel 5.4 oder höher, es ist nicht erforderlich, .dev zu definieren, bitte verwenden Sie stattdessen .test oder andere lokale Domänennamen)
Starten Sie den Entwicklungsserver von Laravel und greifen Sie auf die oben genannte URL zu , sollten Sie die automatisch generierte Swagger-Dokumentation in Ihrem Browser sehen können. 🎜🎜In der Swagger-Dokumentation können Sie die definierte API anzeigen, die API basierend auf den der API hinzugefügten Swagger-Annotationen testen und mögliche Antwortzustände anzeigen. 🎜🎜Zusammenfassung🎜🎜In diesem Artikel haben wir gelernt, wie man mit dem Laravel Swagger-Erweiterungspaket ganz einfach Swagger-API-Dokumentation generiert. Zuerst haben wir Laravel Swagger installiert, dann Swagger gestartet und der API Swagger-Annotationen hinzugefügt. Abschließend haben wir uns die von Laravel Swagger erstellte Dokumentation angesehen. 🎜🎜Die Verwendung von Laravel Swagger kann den Aufwand für das manuelle Schreiben von API-Dokumentation erheblich reduzieren und mögliche Fehler und Inkonsistenzen vermeiden. Durch die Verwendung der Swagger-Benutzeroberfläche können wir die API einfacher anzeigen und testen und gleichzeitig eine entwicklerfreundliche Schnittstelle bereitstellen. 🎜

Das obige ist der detaillierte Inhalt vonLaravel-Entwicklung: Wie verwende ich Laravel Swagger, um API-Dokumentation zu generieren?. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!