Download the PHP package mimosafa/laravel-openapi-validation-helper without Composer

Laravel OpenAPI Validation Helper

日本語のREADMEはこちら

This library provides a helper for transparently validating HTTP requests and responses against an OpenAPI 3.0 schema in Laravel feature tests. It automatically runs validations during your test runs, allowing you to constantly check for discrepancies between your API specification and its implementation.

Features

• Transparent Validation: Utilizes the RequestHandled event to introduce validation with almost no changes to your existing test code.
• Flexible Control: Easily enable or disable request/response validation on a per-test basis.
• API Prefix Support: Handles URL prefixes like /api separately from the schema definition.
• Easy Setup: Get started by simply using a trait in your TestCase and implementing a few methods.
• Detailed Error Reporting: Outputs detailed messages on validation failure, indicating which part of the specification was violated.

Installation

Install via Composer.

Usage

Basic Usage

1. Use the Trait

Use the TestCaseHelper trait in your base test case (usually tests/TestCase.php) or in individual test classes.

2. Call the Setup Method

In your test class's setUp() method, call setUpTransparentlyTest().

3. Implement Required Methods

Implement the three required abstract methods for validation. It is often convenient to define properties in the test class and override their values in each test method to set them dynamically.

4. When API Prefix is Needed

If your application routes have a prefix like /api/users, override the prefix() method.

How it Works

This library does not perform validation directly. Instead, it delegates the core validation logic to the league/openapi-psr7-validator package. The division of responsibilities is as follows:

The TestCaseHelper Trait (This Library)

• Acts as a "bridge".
• It captures the HTTP request and response executed within a Laravel test.
• It converts them into the PSR-7 standard format that league/openapi-psr7-validator can understand.
• During this conversion, it strips any defined prefix (like /api) to align the path with the OpenAPI schema.
• It then hands over the prepared request and response to the validation engine.

The league/openapi-psr7-validator Package

• Acts as the "validation engine".
• It reads the openapi.yml file and fully understands the API specification.
• It automatically determines which schema template (e.g., /users/{id}) corresponds to the concrete path of the request (e.g., /users/456) passed from TestCaseHelper.
• Based on the matched schema definition, it rigorously checks if the request and response contents (parameters, body, headers, etc.) comply with the specification.

This collaboration allows developers to transparently test for OpenAPI specification compliance simply by writing their Laravel tests as they normally would.

API

Required Methods

path(): string

Returns the OpenAPI schema path for the current test.

operation(): HttpRequestMethod

Returns the HTTP method to validate for the current test.

getValidatorBuilder(): ValidatorBuilder

Returns a ValidatorBuilder instance loaded with your OpenAPI schema.

Optional Methods

prefix(): string

Returns the application's routing prefix. Defaults to an empty string. Override this method only if your application uses a prefix.

Validation Control Methods

ignoreRequestCompliance()

Temporarily disables request validation for the current test.

ignoreResponseCompliance()

Temporarily disables response validation for the current test.

HTTP Request Methods

The TestCaseHelper trait overrides the json() and call() methods to automatically set default values when arguments are omitted.

json($method = '', $uri = '', array $data = [], array $headers = [], $options = 0)

When HTTP method and URI are omitted, they are automatically retrieved from operation() and prefix() . path().

call($method = '', $uri = '', $parameters = [], $cookies = [], $files = [], $server = [], $content = null)

Like json(), HTTP method and URI are automatically set to default values when omitted.

Acknowledgements

This library was heavily inspired by the development blog post "LaravelアプリケーションのAPIがSwagger/OpenAPIドキュメントに準拠していることを透過的にテストする" by 株式会社Nextat（ネクスタット）.

I would like to express my deep gratitude to the author for publishing such a wonderful idea and implementation hints.

License

This library is open-sourced software licensed under the MIT license.