README

介绍

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

安装

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

   注意

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

   '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. 为API端点创建测试

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

2. 创建请求类

   <?php
   
   namespace App\Http\Requests;  
   
   use Illuminate\Foundation\Http\FormRequest;
   
   /**
   * @summary Update user
   *
   * @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()方法中删除所有验证规则。此外，您的请求类必须通过依赖注入与控制器连接。插件将从请求类中获取验证规则并生成输入参数的字段描述。

3. 运行测试

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

5. 盈利！

   

注释

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

• @summary - 请求的简短描述
• @description - 实现说明
• @_204 - 响应代码的自定义描述。您可以指定任何您想要的代码。
• @some_field - 来自规则方法的字段的描述

注意

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

配置

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

自定义驱动程序

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

您可以在此处找到驱动程序的示例。

贡献

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

许可

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