README

Laravel到Swagger

此包旨在为您带来为Laravel API创建Swagger / OpenApi 3配置的最简单路径。

安装

仅本地安装请访问此处

composer require riconijeboer/laravel-to-swagger
php artisan vendor:publish --provider="RicoNijeboer\Swagger\SwaggerServiceProvider"
- 这将发布包的配置文件和迁移文件

仅本地安装

composer require riconijeboer/laravel-to-swagger --dev
php artisan vendor:publish --provider="RicoNijeboer\Swagger\SwaggerServiceProvider"
- 这将发布包的配置文件和迁移文件

最后，您应该通过将以下内容添加到您的 composer.json 文件中，防止Swagger包被自动发现：

"extra": {
    "laravel": {
        "dont-discover": [
            "riconijeboer/laravel-to-swagger"
        ]
    }
}

现在自动发现已禁用，您应该在 App\Providers\AppServiceProvider 类的 register 方法中手动注册服务提供者。在示例中，我们仅在 local 环境下启用包。

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    if ($this->app->environment('local')) {
        $this->app->register(\RicoNijeboer\Swagger\SwaggerServiceProvider::class);
    }
}

要求

PHP: 7.4.x 或 8.0.x
Laravel: v6 / v7 / v8

更新

当进行影响现有用户的更改时，我将确保它们在变更日志中得到记录。

这将包含如数据库列添加/删除/重命名等更改。或者需要在您的代码中进行操作的功能性更改。

v2.1.x 到 v2.2.x

当从v2.1更新到v2.2时，请向 swagger_batches 域添加一个可空的 route_domain 字符串列。
$table->string('route_domain')->nullable();

使用

注册Redoc文档路由。

阅读Swagger配置是一种习得品味。为了以更用户友好的方式显示配置，我使用了 Redoc。要注册文档路由，您只需将以下代码添加到您的 routes/web.php 文件或服务提供者中。

use RicoNijeboer\Swagger\Swagger;

Swagger::routes();

自定义 /docs URL

use RicoNijeboer\Swagger\Http\Routing\RouteRegistrar;
use RicoNijeboer\Swagger\Swagger;

Swagger::routes(fn (RouteRegistrar $routes) => $routes->forDocumentation('/different-url/docs'));

自定义路由分组

use RicoNijeboer\Swagger\Swagger;

Swagger::routes(null, [
    'prefix' => 'swagger', // This will do Route::group(['prefix' => 'swagger']) under the hood.
]);

使用Swagger UI代替Redoc

您可以通过将 false 作为 forDocumentation 方法的第二个参数传递，禁用Redoc并使用Swagger UI。

use RicoNijeboer\Swagger\Http\Routing\RouteRegistrar;
use RicoNijeboer\Swagger\Swagger;

Swagger::routes(fn (RouteRegistrar $routes) => $routes->forDocumentation('/docs', false));

注册Swagger配置的路由

要为您的Swagger配置添加路由，请添加 \RicoNijeboer\Swagger\Http\Middleware\SwaggerReader 中间件。该中间件别名为 swagger_reader 和 openapi_reader。

Route::middleware('swagger_reader')->get('products', [ProductController::class,'index']);

标签/分组路由

要将在Swagger中分组多个路由，请向路径添加标签。使用此包，您可以通过向路由添加中间件并传递所需的标签来注册标签，如下所示。

请注意，swagger_tag（《\RicoNijeboer\Swagger\Http\Middleware\SwaggerTag》）中间件仅在批次已存储后才会标记您的请求。如果没有创建批次，它将继续并执行无操作，不问任何问题。

// Using the SwaggerReader middleware
Route::middleware('swagger_reader:tag-one,tag-two')->get('products', [ProductController::class,'index']);

// Using the SwaggerTag middleware
Route::middleware('swagger_tag:tag-one,tag-two')->get('products', [ProductController::class,'index']);

配置

数据库连接

您可能希望将Laravel到Swagger包的数据库条目放在单独的数据库中，或者添加一个额外的前缀。为此，请为您的Laravel项目添加一个额外的连接，并简单地将swagger.database.connection配置值设置。

例如，如果我想将Swagger数据库的所有部分都放在我命名为swagger的连接中，我会按以下方式设置配置。

return [
    //...
    'database' => [
        'connection' => 'swagger',
    ],
    //...
];

评估延迟，配置您的端点多久进行一次重新评估

默认情况下，该包仅在12小时内的几个限制内更新您的路由配置。这确实考虑到了您发送给用户的响应代码。

如果您想将其更改为例如24小时，请将swagger.evaluation-delay配置值设置为秒数。

return [
    //...
    'evaluation-delay' => 24 * 60 * 60, // Or 86400
    //...
];

Swagger元信息

Swagger允许您向用户提供有关您的API的一些信息；标题、描述和版本。

在配置中有一个swagger.info数组，您可以在其中添加您的API的标题、描述和版本，如下所示。

return [
    //...
    'info'             => [
        'title'       => 'Laravel to Swagger',
        'description' => null,
        'version'     => '2.1.2',
    ],
    //...
];

Swagger服务器

Swagger允许您向用户显示您可以从中访问API的服务器。基本设置如下所示；

您有一个API，用户可以访问实时数据，还有一个API，用户可以访问一些演示信息。

return [
    //...
    'servers'          => [
        [
            'url'         => 'http://api.example.com/v1',
            'description' => null,
        ],
        [
            'url'         => 'http://demo-api.example.com/v1',
            'description' => 'The demo environment description',
        ],
    ],
    //...
];

服务器模板

Swagger还支持服务器模板。您可以为服务器添加变量，这使您有机会稍微隐藏URL。

以下是从他们的文档中的示例，其中服务器URL为https://{customerId}.saas-app.com:{port}/v2。这被转换为以下Yaml，他们定义了包含其变量的URL，并描述了变量做什么以及它们的默认值。

Laravel到Swagger支持与Yaml文件基本相同的格式，在Yaml下面，您可以看到如何将其转换为Swagger配置。我为此添加了非常轻的验证，所以如果Swagger UI / Redoc UI中断，请首先确保您已根据Swagger文档正确配置了配置。

Swagger Yaml

servers:
  - url: https://{customerId}.saas-app.com:{port}/v2
    variables:
      customerId:
        default: demo
        description: Customer ID assigned by the service provider
      port:
        enum:
          - '443'
          - '8443'
        default: '443'

Laravel到Swagger配置

return [
    //...
    'servers'          => [
        [
            'url'       => 'https://{customerId}.saas-app.com:{port}/v2',
            'variables' => [
                'customerId' => [
                    'default'     => 'demo',
                    'description' => 'Customer ID assigned by the service provider',
                ],
                'port'       => [
                    'enum'    => [
                        '443',
                        '8443',
                    ],
                    'default' => '443',
                ],
            ],
        ],
    ],
    //...
];

Redoc版本

假设您遇到了Redoc中的一个错误，该错误已在Redoc的新版本中修复，而我没有更新该包以使用修复的版本。我已添加一个配置值（swagger.redoc.version），因此您无需对发布视图或任何内容进行操作；您可以根据他们的发布更改版本，在编写本说明时，最新版本是v2.0.0-rc.53。

return [
    //...
    'redoc' => [
        'version' => 'v2.0.0-rc.53',
        //...
    ],
    //...
];

分组标签

如果您正在使用Redoc，您可以使用配置来按组组织您的标签。以下示例中创建了一个名为“用户管理”的组，包含标签“用户”、“管理员”和“API密钥”。

未由您分组的标签将添加到默认组中，
其名称可以使用配置（swagger.redoc.default-group）更改

return [
    //...
    'redoc' => [
        //...
        'default-group' => null,
        'tag-groups' => [
            [
                'name' => 'User Management',
                'tags' => [ 'Users', 'Admin', 'API keys' ],
            ],
        ],
    ],
    //...
];

添加徽标

您可以通过添加一个完整的URL到swagger.info.logo.url来在Redoc的可视化中侧边栏添加徽标。

徽标仅在您使用Redoc文档路由时显示。

return [
    //...
    'info' => [
        //...
        'logo' => [
            'url' => 'https://picsum.photos/300/200',
        ],
    ],
    //...
];

测试

composer test

riconijeboer / laravel-to-swagger

维护者

详细信息