Laravel-Swagger 项目常见问题解决方案

Laravel-Swagger 项目常见问题解决方案

laravel-swagger Laravel-Swagger is a fully automate tool which allows to generate and save swagger-based documentation after successful completing your application's feature tests. 项目地址: https://gitcode.com/gh_mirrors/lar/laravel-swagger

项目基础介绍

Laravel-Swagger 是一个用于 Laravel 框架的自动化工具，旨在通过成功完成应用程序的功能测试来生成和保存基于 Swagger 的 API 文档。该项目的主要编程语言是 PHP，特别适用于 Laravel 开发者。

新手使用注意事项及解决方案

1. 安装包时遇到版本兼容性问题

问题描述：在安装 Laravel-Swagger 包时，可能会遇到与 Laravel 或 PHP 版本不兼容的问题。

解决步骤：

1. 检查 Laravel 版本：确保你的 Laravel 版本在 5.5 或更高版本。对于 5.5 或更高版本，包会自动发现。
2. 检查 PHP 版本：确保你的 PHP 版本在 7.2 或更高版本。
3. 手动添加服务提供者：如果使用的是较旧的 Laravel 版本，需要在 config/app.php 文件中手动添加服务提供者：

   'providers' => [
       RonasIT\AutoDoc\AutoDocServiceProvider::class,
   ]
   

2. 文档生成失败

问题描述：在运行测试后，文档未能成功生成。

解决步骤：

1. 检查测试文件：确保你的测试文件中使用了 \RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait 特性。
2. 配置文档保存：确保在 phpunit.xml 文件中正确配置了文档保存方式。例如：

   <phpunit>
       <extensions>
           <bootstrap class="RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension"/>
       </extensions>
       <testsuites>
           <testsuite name="Feature">
               <directory suffix="Test.php">/tests/Feature</directory>
           </testsuite>
       </testsuites>
   </phpunit>
   

3. 运行命令：在测试完成后，运行 php artisan swagger:push-documentation 命令生成文档。

3. 文档未更新

问题描述：文档生成后，API 更新但文档未随之更新。

解决步骤：

1. 重新运行测试：确保在 API 更新后重新运行测试，以生成最新的文档。
2. 清除旧文档：在生成新文档之前，可以手动删除旧的文档文件，避免旧文档的干扰。
3. 自动化脚本：考虑编写一个自动化脚本，在每次部署或测试运行后自动生成和推送文档。

通过以上步骤，新手可以更好地使用 Laravel-Swagger 项目，避免常见问题并顺利生成 API 文档。

laravel-swagger Laravel-Swagger is a fully automate tool which allows to generate and save swagger-based documentation after successful completing your application's feature tests. 项目地址: https://gitcode.com/gh_mirrors/lar/laravel-swagger