Weave Code
Laravel Openapi Validator Laravel Package
kirschbaum-development/laravel-openapi-validator
Validate Laravel requests and responses against your OpenAPI (Swagger) specification. Catch schema mismatches early with middleware, clear error messages, and minimal setup, keeping your API contract and documentation in sync.
Automatic OpenAPI validation for Laravel HTTP tests
Frequently asked questions about Laravel Openapi Validator
- How do I install and configure kirschbaum-development/laravel-openapi-validator?
- Install it with Composer using composer require kirschbaum-development/laravel-openapi-validator, then publish the package config and point it at the path of your OpenAPI 3 document. From there you either use the provided helpers inside your Laravel HTTP tests or attach the middleware to a route group. There is no database, queue, event, or container coupling, so setup is essentially config plus a route-group entry. Plan the bulk of the effort as spec authoring rather than wiring.
- Can I validate API responses in my Laravel feature tests?
- Yes. The package was built primarily for Laravel's HTTP test suite, where it validates both the request your test sends and the response your application returns against the operations defined in your OpenAPI document. Response validation is the higher-value half of contract testing because it catches schema drift in payloads consumers actually receive. Be aware that it also raises CPU cost per test and increases exposure to false positives, so treat enabling response assertions as a deliberate decision rather than a bundled default.
- Should I run OpenAPI validation as middleware in production?
- You can, but it is a separate program of work from test-time validation with a different risk profile. Every request is adapted from Laravel to PSR-7 and back through symfony/psr-http-message-bridge, which is real per-request work, and a validation failure is customer-visible. Get a capacity review and on-call sign-off, and start by scoping the middleware to a single route group so rollback is a routing change rather than an architecture decision. Most teams get most of the value from CI and feature tests alone.
- Which OpenAPI versions does laravel-openapi-validator support?
- It validates against OpenAPI 3 documents, which is what the package expects you to point it at. The engine underneath is a PSR-7 based OpenAPI validator reached through symfony/psr-http-message-bridge, so the fidelity of your document drives the quality of the results. Legacy Swagger 2.0 definitions need to be converted to OpenAPI 3 first, since the package is a validator rather than a spec converter or linter.
- Which Laravel and PHP versions does this package support?
- The package is a thin Laravel adapter and its hard constraint comes from its Symfony PSR HTTP message bridge dependency, so the effective PHP floor and Laravel compatibility follow whatever bridge version Composer resolves for you. Release 2.0.2 only widened the accepted constraint to include bridge v8, which tracks Symfony 8 and can raise the PHP requirement on modern stacks. Check composer.json against your application before upgrading, and pin 2.0.2 explicitly instead of floating on ^2.0 so a transitive resolution change cannot slide through review.
- What happens when a request or response fails OpenAPI validation?
- Validation failures surface as detailed Laravel exceptions in tests and as HTTP error responses when the middleware is in the request path, with messages describing the mismatch so you can trace it back to a specific path in the spec. In tests that means a failing assertion rather than a silent pass, which is the whole point of the tool. Decide early whether consumers see the package's default Laravel-shaped error or your house error envelope, because changing that later is an API governance decision, not a config tweak. Also define what happens when the spec itself cannot be loaded or parsed.
- Why am I getting false positives, and how do I fix them?
- Almost all early false positives are defects in the OpenAPI document, not in your application code. Common culprits are nullable handling, oneOf and anyOf branches, format assertions such as date-time and uuid, deep $ref graphs, and error envelope definitions that do not match what the framework actually returns. Fixing them is spec-authoring work with a named owner on the API-contract side, budgeted in days to weeks, and unaddressed triage is the most common reason these initiatives get switched off within a quarter.
- Does this package generate documentation, SDKs, or mock servers?
- No. It deliberately does one thing: validating HTTP requests and responses against an OpenAPI document. It does not generate SDKs, serve mocks, lint specs, or produce developer documentation, so it composes with whatever spec tooling you already run instead of replacing it. That narrow scope is why it fits cleanly into a delivery pipeline without touching your product architecture.
- What are the alternatives to laravel-openapi-validator?
- The closest alternative is using the underlying league/openapi-psr7-validator directly, which gives more control but also more adapter code to maintain. Broader contract-testing tools such as Pact take a consumer-driven approach rather than validating against a single spec, while Dredd-style tools test a live server against a spec from the outside. Hand-written JSON assertions in feature tests are cheaper up front but drift from your documentation over time, which is the exact problem this package targets.
- Is this package actively maintained, and how risky is depending on it?
- It is a single-vendor, MIT-licensed package with a modest star count and few recorded dependents, so treat it as a narrow, replaceable adapter rather than load-bearing tier-1 infrastructure. The upside is that it is thin enough to vendor or fork, which materially caps abandonment risk and makes the exit plan a fork rather than a re-platform. Pin the exact version, keep a lockfile check in CI, and let the test-time use case carry the value before considering runtime enforcement.
Weaver
How can I help you explore Laravel packages today?