README

Laravel Swagger插件

与其他文档生成器的比较

介绍

此插件旨在在通过PHPUnit测试时生成REST API的文档。

安装

1. 使用以下命令安装包：composer require ronasit/laravel-swagger

   注意

   对于Laravel 5.5或更高版本，包将自动发现。对于旧版本，将AutoDocServiceProvider添加到config/app.php中的providers数组中，如下所示

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

2. 运行php artisan vendor:publish

3. 将\RonasIT\Support\AutoDoc\Http\Middleware\AutoDocMiddleware::class中间件添加到Http/Kernel.php中的全局HTTP中间件堆栈。

4. 将\RonasIT\Support\AutoDoc\Tests\AutoDocTestCaseTrait特质添加到tests/TestCase.php

5. 使用以下方法之一配置文档保存

• 将SwaggerExtension添加到phpunit.xml的<extensions>块中。请注意，此方法将在更新PHPUnit到10版本后删除 (sebastianbergmann/phpunit#4676)

  <extensions>
      <extension class="RonasIT\Support\AutoDoc\Tests\PhpUnitExtensions\SwaggerExtension"/>
  </extensions>
  <testsuites>
      <testsuite name="Feature">
          <directory suffix="Test.php">./tests/Feature</directory>
      </testsuite>
  </testsuites>

• 在CI/CD配置中tests阶段之后调用php artisan swagger:push-documentation控制台命令

用法

基本用法

1. 创建请求类

   <?php
   
   namespace App\Http\Requests;  
   
   use Illuminate\Foundation\Http\FormRequest;
   
   /**
   * @summary Update user
   *
   * @deprecated 
   *
   * @description
   * This request should be used for updating the user data
   *
   * @_204 Successful
   * 
   * @is_active will indicate whether the user is active or not
   */
   class UpdateUserDataRequest extends FormRequest
   {
       /**
        * Determine if the user is authorized to make this request.
        *
        * @return bool
        */
       public function authorize()
       {
           return true;
       }  
   
       /**
        * Validation Rules
        *
        * @return array
        */
       public function rules()
       {
           return [
               'name' => 'string',
               'is_active' => 'boolean',
               'age' => 'integer|nullable'
           ];
       }
   }

   注意

   为了插件正确工作，您必须在请求类的rules()方法中处理所有验证规则。此外，您的请求类必须通过依赖注入与控制器连接。插件将从请求类中获取验证规则并生成输入参数的字段描述。

2. 为您的路由创建一个控制器和方法

   <?php
   
   namespace App\Http\Controllers;
   
   use App\Http\Requests\Users\UpdateUserDataRequest;
   
   class UserController extends Controller
   {
       public function update(UpdateUserDataRequest $request, UserService $service, $id)
       {
           // do something here...
   
           return response('', Response::HTTP_NO_CONTENT);
       }
   }

   注意

   请求类的依赖注入是可选的，但如果不存在，API文档中的“参数”块将为空。

3. 为API端点创建测试

   public function testUpdate()
   {
       $response = $this->json('put', '/users/1', [
           'name': 'Updated User',
           'is_active': true,
           'age': 22
       ]);
   
       $response->assertStatus(Response::HTTP_NO_CONTENT);
   }

4. 运行测试

5. 转到auto-doc.route配置中定义的路由

6. 成功！

   

注解

您可以在请求类中使用以下注解来自定义API端点的文档

• @summary - 请求的简短描述
• @description - 实现说明
• @_204 - 自定义响应代码的描述。您可以指定任何所需的代码。
• @some_field - 从规则方法中的字段描述
• @deprecated - 标记路由为已弃用

注意

如果您不使用请求类，摘要、描述和参数将为空。

配置

• auto-doc.route - 生成文档的路由
• auto-doc.basePath - 您API的根目录

自定义驱动器

您可以通过创建自己的自定义驱动器来指定收集文档的方式。

您可以在这里找到驱动器的示例。

查看OpenAPI文档

从版本2.2开始，该包包括在OpenAPI文档查看器之间切换的能力。要访问不同的查看器，修改documentation_viewer配置。此更改将立即反映，无需重新构建文档文件。

合并额外文档

该软件包支持将主文档与在additional_paths配置中指定的附加有效OpenAPI文件集成。

贡献

感谢您考虑为Laravel Swagger插件做出贡献！贡献指南可在贡献指南中找到。

许可证

Laravel Swagger插件是开源软件，许可协议为MIT许可证。