README

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

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

安装

您可以通过 composer 安装此包。

composer require wotz/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 文件。如果您在 Laravel 项目中找不到 OpenAPI 文件，也可以提供 URL。您还可以在此处为相同的 api 定义多个版本。

// in config/swagger-ui.php

return [
    // ...

    'path' => 'swagger',

    'versions' => [
        'v1' => resource_path('swagger/openapi.json')
    ],

    // ...
];

默认情况下，包将自定义 OpenAPI 文件中的服务器 URL 和 oauth URL 为 Laravel 应用程序的基本 URL。您可以在配置中禁用此功能。

// in config/swagger-ui.php

return [
    // ...

    'modify_file' => true,

    // ...
];

您还可以设置 oauth 客户端 ID 和客户端密钥。这些值将自动填充在 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.debrauwer@whoownsthezebra.be 而不是使用问题跟踪器。

鸣谢

• Günther Debrauwer
• 所有贡献者

许可

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