radebatz/openapi-verifier

验证JSON(API响应)是否符合OpenAPI规范。

2.0.0 2024-03-25 00:50 UTC

This package is auto-updated.

Last update: 2024-08-27 01:14:59 UTC


README

build Coverage Status License: MIT

介绍

允许您将API项目的控制器响应与给定的OpenAPI规范进行验证。

要求

安装

您可以使用composer或简单地下载发布版

Composer

首选方法是使用composer。如果您尚未安装composer,请遵循安装说明

安装composer后,在项目根目录中执行以下命令以安装此库

composer require radebatz/openapi-verifier

之后,所有必需的类都应可用于项目中以添加路由支持。

使用方法

手动验证

VerifiesOpenApi特质可以直接使用并按以下3种方式定制,以提供所需的OpenApi规范

  • 覆盖以下方法getOpenApiSpecificationLoader()
  • 填充$openapiSpecificationLoader属性。
  • 创建一个指向规范文件的属性$openapiSpecification
<?php

namespace Tests\Feature;

use Radebatz\OpenApi\Verifier\VerifiesOpenApi;
use Radebatz\OpenApi\Verifier\OpenApiSpecificationLoader;
use PHPUnit\Framework\TestCase;

class UsersTest extends TestCase
{
    use VerifiesOpenApi;
    
    /** @inheritdoc */
    protected function getOpenApiSpecificationLoader(): ?OpenApiSpecificationLoader
    {
        return new OpenApiSpecificationLoader(__DIR__ . '/specifications/users.yaml');
    }

    /** @test */
    public function index()
    {
        // PSR client
        $client = $this->client();
        $response = $client->get('/users');

        $this->assertEquals(200, $response->getStatusCode());
        
        // will throw OpenApiSchemaMismatchException if verification fails
        $this->verifyOpenApiResponseBody('get', '/users', 200, (string) $response->getBody());
    }
}

Laravel适配器

适配器将按照以下顺序动态解析规范

  • 传递给registerOpenApiVerifier()的文件名
  • /tests/openapi.json
  • /tests/openapi.yaml
  • 通过扫描app文件夹从头开始生成规范

代码期望在Laravel Test\TestCase的上下文中。

<?php

namespace Tests\Feature;

use Radebatz\OpenApi\Verifier\Adapters\Laravel\OpenApiResponseVerifier;
use Tests\TestCase;

class UsersTest extends TestCase
{
    use OpenApiResponseVerifier;

    public function setUp(): void
    {
        parent::setUp();

        $this->registerOpenApiVerifier(/* $this->>createApplication() */ /* , [specification filename] */);
    }

    /** @test */
    public function index()
    {
        // will `fail` if schema found and validation fails
        $response = $this->get('/users');

        $response->assertOk();
    }
}

Slim适配器

适配器将按照以下顺序动态解析规范

  • 传递给registerOpenApiVerifier()的文件名
  • /tests/openapi.json
  • /tests/openapi.yaml
  • 通过扫描src文件夹从头开始生成规范

最简单的方法是在Tests\Functional\BaseTestCase中注册验证器。

<?php

namespace Tests\Functional;

use ...
use Radebatz\OpenApi\Verifier\Adapters\Slim\OpenApiResponseVerifier;
use PHPUnit\Framework\TestCase;

class BaseTestCase extends TestCase
{
    use OpenApiResponseVerifier;

    public function runApp($requestMethod, $requestUri, $requestData = null)
    {
        ...
        
        $app = new App();
        
        // register OpenApi verifier
        $this->registerOpenApiVerifier($app, __DIR__ . '/../specifications/users.yaml');
        
        ...
    }
}
<?php

namespace Tests\Functional;

class UsersTest extends BaseTestCase
{
    /** @test */
    public function index()
    {
        // will `fail` if schema found and validation fails
        $response = $this->runApp('GET', '/users');

        $this->assertEquals(200, $response->getStatusCode());
    }
}

许可证

openapi-verifier项目是在MIT许可证下发布的。