README

此插件旨在在测试通过的同时收集关于您的Rest-Api的信息并生成文档。其操作原理基于在您想要收集信息的路由上安装的特殊中间件，在所有测试成功完成后生成Swagger文件。此外，此插件还能够绘制Swagger模板以显示为配置生成的文档。

安装

Composer

1. composer require tenantcloud/laravel-auto-generate-swagger

Laravel

1. 将 RonasIT\Support\AutoDoc\AutoDocServiceProvider::class, 添加到 config/app.php 中的 providers。
2. 运行 php artisan vendor:publish

插件

1. 将中间件 \RonasIT\Support\AutoDoc\Http\Middleware\AutoDocMiddleware::class 添加到 Http/Kernel.php。
2. 在 tests/TestCase.php 中使用 \RonasIT\Support\AutoDoc\Tests\AutoDocTestCaseTrait。
3. 在 config/swagger.php 中，您可以指定插件的启用，项目的信息，一些默认描述和渲染文档的路由。
4. 在 .env 文件中，您应该添加以下行 LOCAL_DATA_COLLECTOR_PROD_PATH=/example-folder/documentation.json LOCAL_DATA_COLLECTOR_TEMP_PATH=/tmp/documentation.json

用法

为了正确运行插件，您必须在类 YourRequest 的 rules() 方法中处理所有验证规则，该类必须通过 DependencyInjection 连接到控制器。插件将从您的请求中获取验证规则并将其用作输入参数的描述。

示例

<?php

namespace App\Http\Requests;  

use Illuminate\Foundation\Http\FormRequest;

/**
 * @summary Updating of user
 *
 * @description
 *  This request mostly needed to specity flags <strong>free_comparison</strong> and 
 *  <strong>all_cities_available</strong> of user
 *
 * @_204 Successful MF!
 */
class UpdateUserDataRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }  
  
    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            'all_cities_available' => 'boolean',
            'free_comparison' => 'boolean'
        ];
    }
}

在自定义请求的注解中，您可以指定请求的摘要和描述。

<?php

namespace App\Http\Controllers;  

use App\Http\Requests\UpdateRequest;

class UpdateController
{ 

/**
 * @tag json-api
 * @summary Updating of user
 *
 * @description
 *  This request mostly needed to specity flags <strong>free_comparison</strong> and 
 *  <strong>all_cities_available</strong> of user
 *
 * @_204 Successful MF!
 */
   public function update(int $id, UpdateRequest $request)
   {
       //...
   }
}

• @tag - 为请求添加标签
• @summary - 请求的简短描述
• @description - 实现说明
• @_204 - 响应代码的自定义描述。您可以指定任何您想要的代码。

如果您没有创建 Request 类，摘要、实现说明和参数将为空。插件将仅收集响应代码和示例。

如果您没有为请求创建注解，摘要将自动从请求名称生成。例如，请求 UpdateUserDataRequest 将有摘要 Update user data request。

如果您没有为代码描述创建注解，它将按照以下优先级自动生成

1. 请求注解
2. 来自 swagger.defaults.code-descriptions.{$code} 的默认描述
3. Symfony\Component\HttpFoundation\Response::$statusTexts 的描述

关于配置的说明

• swagger.route - 这是将位于生成的文档的路由
• swagger.basePath - 这是您的API根的路由

您还可以通过创建自定义数据收集器类来指定收集文档的方式。