radebatz / openapi-verifier
验证JSON(API响应)是否符合OpenAPI规范。
2.0.0
2024-03-25 00:50 UTC
Requires
- php: >=8.1
- ext-json: *
- justinrainbow/json-schema: ^5.2.13
- nyholm/psr7: ^1.1
- nyholm/psr7-server: ^1.0
- psr/http-message: ^2.0
- symfony/psr-http-message-bridge: ^6.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.47.1
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.0
- symfony/yaml: ^6.0|^7.0
- zircote/swagger-php: ^4.8
Suggests
- laravel/laravel: A PHP framework
- slim/slim: A PHP framework
- zircote/swagger-php: OpenApi library to generate OpenAPI documentation from PHP annotations.
README
介绍
允许您将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许可证下发布的。