README

此软件包使您能够轻松地将项目的 Swagger（OpenAPI v3 JSON）文件在 Laravel 应用程序中的 Swagger UI 中访问。

Swagger UI 将自动使用您当前的项目环境。它将您的 API 基础 URL 设置为活动基础 URL。还支持通过配置文件将可能的 OAuth2 配置（如 URL 和 client-id/client-secret）注入 Swagger UI。

安装

您可以通过 composer 安装此软件包

composer require nextapps/laravel-swagger-ui

安装 Laravel Swagger UI 后，使用 swagger-ui:install Artisan 命令发布其服务提供者和配置文件。

php artisan swagger-ui:install

用法

Swagger UI 在 /swagger 处暴露。默认情况下，您只能在本地环境中访问它。在您的 app/Providers/SwaggerUiServiceProvider.php 文件中，有一个 gate 方法。此授权门控控制非本地环境中对 Swagger UI 的访问。您可以根据需要修改此门控以限制对您的 Swagger UI 和 Swagger（OpenAPI v3）文件的访问

/**
 * Register the Swagger UI gate.
 *
 * This gate determines who can access Swagger UI in non-local environments.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewSwaggerUI', function ($user = null) {
        return in_array(optional($user)->email, [
            //
        ]);
    });
}

在发布的 config/swagger-ui.php 文件中，您可以编辑 Swagger UI 的路径和 Swagger（OpenAPI v3）文件的存储位置。默认情况下，软件包期望在 'resources/swagger' 目录中找到 OpenAPI json 文件。

// in config/swagger-ui.php

return [
    // ...

    'path' => 'swagger',

    'file' => resource_path('swagger/openapi.json'),

    // ...
];

您还可以自定义 OAuth 设置。默认情况下，OAuth 路径是基于 Laravel Passport 配置的。您还可以设置 client ID 和 client secret。这些值将在 Swagger UI 的认证视图中自动填写。

// in config/swagger-ui.php

return [
    // ...

    'oauth' => [
        'token_path' => 'oauth/token',
        'refresh_path' => 'oauth/token',
        'authorization_path' => 'oauth/authorize',

        'client_id' => env('SWAGGER_UI_OAUTH_CLIENT_ID'),
        'client_secret' => env('SWAGGER_UI_OAUTH_CLIENT_SECRET'),
    ];

    // ...
];

测试

composer test

代码检查

composer lint

变更日志

有关最近更改的详细信息，请参阅 变更日志。

贡献

有关详细信息，请参阅 贡献指南。

安全

如果您发现任何与安全相关的问题，请通过电子邮件 gunther@nextapps.be 联系，而不是使用问题跟踪器。

鸣谢

• Günther Debrauwer
• 所有贡献者

许可

MIT 许可证（MIT）。有关更多信息，请参阅 许可文件。