README

基于 OpenAPI 规范的请求和响应验证器。

摘要

使用预先准备的 OpenAPI Spec 验证任何请求和响应。
自动从 Laravel OpenAPI 或 L5 Swagger 加载规范。
您也可以在不使用这些库的情况下加载自己的规范。
您可以根据路由或应用范围自定义验证和错误日志行为。
可以显示 Swagger UI。您可以看到文档并测试 API。

需求

PHP 8.1 或更高版本
Laravel 9.0 或更高版本

安装

您可以通过 composer 安装此包

composer require kentaroutakeda/laravel-openapi-validator

使用方法

配置 OpenAPI 规范

如果您正在使用 Laravel OpenAPI，您不需要做任何事情。

对于 L5 Swagger，需要以下设置
```
# .env
OPENAPI_VALIDATOR_PROVIDER="l5-swagger"
```
如何在不使用这些包的情况下加载自己的模式将在后面解释。
注册中间件
```
Route::get('/example', ExampleController::class)
    ->middleware(OpenApiValidator::class); // <- Add this line
```
具有此设置的路线将验证所有请求，包括功能测试，以及根据设置，响应。

注意
此存储库的 ./e2e 目录包含 e2e 测试的工作示例。您可以在路由中看到中间件配置示例，以及在测试中的实际验证和失败。
(可选) 自定义中间件

如果需要，您可以为每个路由更改中间件的行为。
```
Route::get('/', ExampleController::class)
  ->middleware(OpenApiValidator::config(
    provider: 'admin-api', // <- Use spec other than default
    skipResponseValidation: true // <- Skip Response Validation
  ));
```
注意
对大量数据进行响应验证可能需要很长时间。根据路由和 APP_* 环境变量开启/关闭验证可能是一个好主意。
部署

当您将应用程序部署到生产环境时，您应该确保在部署过程中运行 openapi-validator:cache Artisan 命令
```
php artisan openapi-validator:cache
```
此命令缓存了应用程序中定义的 OpenAPI 规范。如果您更改开发中的定义，您需要清除它，如下所示
```
php artisan openapi-validator:clear
```

(可选) Swagger UI 支持

您只需安装包即可查看 Swagger UI。无需进行其他配置。

安装包。

composer require --dev swagger-api/swagger-ui

在浏览器中显示 APP_URL/openapi-validator/documents。
```
open https://:8000/openapi-validator/documents
```

注意
默认情况下，Swagger UI 仅在启用 APP_DEBUG 时显示。

(可选) 自定义

发布配置

您可以通过发布配置文件来更改行为。

php artisan openapi-validator:publish

或者，大多数设置都可以使用环境变量进行更改。请参阅 config/openapi-validator.php 中的注释以获取详细信息。

您自己的模式提供者

如果您想使用您自己的模式提供者，首先发布配置。

接下来，实现一个用于检索模式的类。

class MyResolver implements ResolverInterface
{
  public function getJson(array $options): string
  {
    // This example assumes that the schema exists in the root directory.
    return File::get(base_path('openapi.json'));
  }
}

最后，将其设置在您的配置中。

return [
  // Set the provider name.
  'default' => 'my-resolver',

  'providers' => [
    // Set the provider name you created.
    'my-resolver' => [
      // Specify the class you created in the `resolver` parameter.
      'resolver' => MyResolver::class,
    ],
  ],
];

错误响应和自定义

默认情况下，它根据 RFC 7807 - HTTP API 的问题详情格式化。

根据您的设置，验证错误、堆栈跟踪和原始响应也可以包含在内。例如，它可能看起来像这样

{
  "title": "NoResponseCode",
  "detail": "OpenAPI spec contains no such operation [/,get,201]", // Error reason
  "status": 500, // Same as HTTP response code
  "originalResponse": { "status": "201" }, // Original response before validation
  "trace": [
    { "error": "...", "message": "...", "file": "...", "line": 42 },
    { "...": "..." }
  ]
}

以下是更改到不同格式的示例

首先，实现一个生成响应的类。例如

class MyErrorRenderer implements ErrorRendererInterface
{
  public function render(
    Request $request,
    \Throwable $error,
    ErrorType $errorType,
  ): Response {
    return new Response(
      match ($errorType) {
        ErrorType::Request => "Request Error: " . $error->getMessage(),
        ErrorType::Response => "Response Error: " . $error->getMessage(),
      }
    );
  }
}

接下来，将类注册到服务容器中。

// AppServiceProvider.php

public function register(): void
{
  $this->app->bind(
    ErrorRendererInterface::class,
    MyErrorRenderer::class
  );
}

事件

如果发生验证错误，将根据错误类型触发事件。

ValidationFailedInterface - 所有错误
- RequestValidationFailed - 请求验证错误
- ResponseValidationFailed - 响应验证错误

贡献和开发

请随意打开一个问题或添加一个拉取请求。

在添加拉取请求时，请参考以下设置步骤。

# Clone this repository and move to the directory.
git clone https://github.com/KentarouTakeda/laravel-openapi-validator.git
cd laravel-openapi-validator

# Install dependencies.
composer install

# (Optional) Install tools: The commit hook automatically formats the code.
npm install

# Run tests.
vendor/bin/phpunit

许可证

Laravel OpenAPI Validator 是一个开源软件，许可协议为 MIT 许可协议。

kenitaroutakeda / laravel-openapi-validator

维护者

详细信息