README

此包使得在 Laravel 应用程序中轻松访问项目的 Swagger (OpenAPI v3 JSON) 文件。

Swagger UI 将自动使用当前项目环境。它将 api 的基本 URL 设置为活动的基本 URL。可能的 oauth2 配置，例如 URL 和 client-id/client-secret，也可以通过配置文件注入到 Swagger UI 中。

安装

您可以通过 composer 安装此包

composer require james.rus52/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

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全

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

鸣谢

• Anton V. Davydov
• 所有贡献者

许可

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