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.
Utilisez Composer pour installer le package d'extension Laravel Swagger :
composer require darkaonline/l5-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, ],
为了告诉 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
注释示例了可能的响应状态。
在完成所有先前的步骤之后,我们可以使用以下 URL 来查看 Laravel Swagger 文档:
http://your-app.dev/api/documentation
(请注意,如果您使用的是 Laravel 5.4 或以上版本,则无需定义 .dev
,请改为使用 .test
config/app.php
: rrreee
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.
rrreeeDans 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!