README

此包可轻松将项目的Swagger（OpenAPI v3 JSON或YAML）文件在Laravel应用程序的Swagger UI中访问。

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文件。您也可以提供URL，如果OpenAPI文件不在Laravel项目中，也可以定义相同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）。有关更多信息，请参阅许可文件。