README

基于 n1215/openapi-http-foundation-validator 的 Laravel (v3) OpenAPI 验证。

要求

• PHP >= 8.1
• Laravel >= 9.0

安装

composer require n1215/openapi-laravel-validator

用法

1. 创建您的 OpenAPI 规范文件

创建一个 YAML 文件或 JSON 文件。

示例: hello.yaml

2. 创建服务提供者

<?php

declare(strict_types=1);

namespace App\Providers;

use Illuminate\Support\Facades\Cache;
use N1215\OpenApiValidation\HttpFoundation\ValidatorBuilder;
use N1215\OpenApiValidation\Laravel\OpenApiLaravelValidatorServiceProvider;

class OpenApiValidatorServiceProvider extends OpenApiLaravelValidatorServiceProvider
{
    protected function makeValidationBuilder(): ValidatorBuilder
    {
        $httpMessageFactory = $this->makeHttpMessageFactory();
        return (new ValidatorBuilder($httpMessageFactory))
            ->fromYamlFile('/path/to/your-definition.yaml')
            ->setSimpleCache(Cache::store(), 3600);
    }
}

3. 在 HTTP 测试中使用 AssertsWithOpenApi 特性

简单使用特性来自动验证请求和响应。

<?php

declare(strict_types=1);

namespace Tests\Feature;

use Tests\TestCase;
use N1215\OpenApiValidation\Laravel\Test\AssertsWithOpenApi;

class GetHelloTest extends TestCase
{
    use AssertsWithOpenApi;

    public function testSuccess(): void
    {
        $response = $this->json(
            'get',
            '/hello?name=Taro'
        );

        $response->assertOk();
        $response->assertJson(['message' => 'Hello, Taro']);
    }

    public function testValidationFailed(): void
    {
        // disable request validation for invalid request parameters
        $this->disableRequestAssertion();

        $response = $this->json(
            'get',
            '/hello'
        );

        $response->assertStatus(422);
        $response->assertJsonValidationErrors(['name' => 'The name field is required']);
    }
}

4. 使用 ValidateWithOpenAPi 中间件

您可以按需更改响应。

<?php

declare(strict_types=1);

namespace App\Http\Middleware;

use N1215\OpenApiValidation\RequestValidationFailed;
use N1215\OpenApiValidation\ResponseValidationFailed;
use Symfony\Component\HttpFoundation\Response;

class ValidateWithOpenApi extends \N1215\OpenApiValidation\Laravel\Middleware\ValidateWithOpenApi
{
    protected function makeRequestValidationFailedResponse(RequestValidationFailed $e): Response
    {
        return $this->responseFactory->json(
            [
                'message' =>  'failed to validate request',
            ],
            Response::HTTP_BAD_REQUEST
        );
    }

    protected function makeResponseValidationFailedResponse(ResponseValidationFailed $e): Response
    {
        return $this->responseFactory->json(
            [
                'message' =>  'failed to validate response',
            ],
            Response::HTTP_INTERNAL_SERVER_ERROR
        );
    }
}