Développement Laravel : Comment utiliser Laravel Swagger pour générer de la documentation API ?

Développement Laravel : Comment utiliser Laravel Swagger pour générer de la documentation API ?

Travailler avec la documentation API est souvent une tâche fastidieuse mais essentielle lors du développement d'applications Web. Utilisez Swagger pour générer et visualiser automatiquement la documentation de l'API. Dans le développement de Laravel, nous pouvons utiliser le package d'extension Laravel Swagger pour générer facilement la documentation de l'API Swagger. Cet article vous expliquera comment utiliser Laravel Swagger avec Laravel.

1. Installez Laravel Swagger

Utilisez Composer pour installer le package d'extension Laravel Swagger :

composer require darkaonline/l5-swagger

2. Configurez Laravel Swagger

Laravel Swagger dépend de l'interface utilisateur de Swagger, nous devons donc publier les ressources de l'interface utilisateur de Swagger dans le répertoire public de Laravel. . Utilisez la commande suivante pour terminer la publication :

php artisan vendor:publish --provider "L5SwaggerL5SwaggerServiceProvider"

Après avoir exécuté la commande de publication, vous verrez le répertoire swagger-ui sous le répertoire public/vendor. Swagger UI toutes les ressources. 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，请改为使用 .test

Ensuite, ajoutez la ligne suivante au fichier de configuration de Laravel config/app.php :

rrreee

Ajoutez une annotation Swagger

Pour dire à Laravel que Swagger ne déduit pas Format API, nous devons ajouter des annotations Swagger dans le code. Ces annotations permettent à Laravel Swagger d'analyser automatiquement votre API et de générer la documentation correspondante.

rrreee

Dans l'exemple ci-dessus, nous avons utilisé l'annotation @OAGet pour indiquer qu'il s'agit d'une requête GET. L'annotation path définit le chemin d'accès à l'API. Les annotations tags et summary sont utilisées pour afficher des résumés et des balises dans les documents Swagger. Enfin, l'annotation @OAResponse illustre les états de réponse possibles.

Afficher la documentation Swagger dans Laravel

🎜🎜Après avoir terminé toutes les étapes précédentes, nous pouvons utiliser l'URL suivante pour afficher la documentation de Laravel Swagger : 🎜rrreee🎜 (Veuillez noter que si vous utilisez Laravel 5.4 ou supérieur, il n'est pas nécessaire de définir .dev, veuillez utiliser .test ou d'autres noms de domaine locaux à la place) 🎜🎜Démarrez le serveur de développement de Laravel et accédez à l'URL ci-dessus, vous devriez pouvoir voir la documentation Swagger générée automatiquement dans votre navigateur. 🎜🎜Dans la documentation Swagger, vous pouvez afficher l'API définie, tester l'API en fonction des annotations Swagger ajoutées à l'API et afficher les états de réponse possibles. 🎜🎜Résumé🎜🎜Dans cet article, nous avons appris comment générer facilement la documentation de l'API Swagger à l'aide du package d'extension Laravel Swagger. Tout d'abord, nous avons installé Laravel Swagger, puis démarré Swagger et ajouté des annotations Swagger à l'API. Enfin, nous avons examiné la documentation générée par Laravel Swagger. 🎜🎜L'utilisation de Laravel Swagger peut réduire considérablement la charge de rédaction manuelle de la documentation de l'API et éviter d'éventuelles erreurs et incohérences. En utilisant l'interface utilisateur Swagger, nous pouvons visualiser et tester plus facilement l'API, tout en fournissant une interface conviviale pour les développeurs. 🎜

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!