Openapi Bundle Laravel Package

Getting Started

This is nijens/openapi-bundle, a Symfony bundle for OpenAPI-driven request validation and parameter handling. In a Laravel codebase it is not a drop-in package: Laravel does not load Symfony bundles automatically. Treat it as a strong reference implementation or use it in a Symfony service that shares your OpenAPI contract.

Minimal steps in a Symfony host:

1. composer require nijens/openapi-bundle
2. Register the bundle in config/bundles.php
3. Point configuration at your OpenAPI spec file
4. Annotate or configure the controller/action that should be validated
5. Start with one endpoint and one required header

First useful use case: validate a required header such as X-Tenant-Id or Authorization before the controller runs. In 3.1.0 this is the lowest-friction feature to adopt because it does not require changing your response models or DTO layer.

In Laravel, first look at the package’s request-validation and deserialization classes rather than the bundle bootstrapping. If you only need header validation, a small Laravel middleware backed by your OpenAPI spec may be simpler than adopting the bundle wholesale.

Implementation Patterns

Header validation as middleware-like guardrails. Declare headers in the OpenAPI spec, then let the bundle validate presence, type, and format. Use this for auth, tenant, correlation, API-version, and idempotency headers.

Deserialize parameters into objects. 3.1.0 adds parameter deserialization into deserialization objects. Use this to replace manual $request->query('page') / (int) casting with typed DTOs:

final class Pagination
{
    public function __construct(
        public readonly int $page = 1,
        public readonly int $perPage = 20,
    ) {}
}

Map query/path/header parameters to DTOs and validate the DTO after deserialization. This keeps controllers thin and makes parameter rules testable.

Spec-first workflow. Keep the OpenAPI file in the repo. Update the spec and the DTO together. Run spec linting in CI and exercise one happy-path and one failing request per endpoint.

Shared contract across Laravel and Symfony services. If your Laravel app calls a Symfony service using this bundle, generate clients from the same spec. The new header validation and object deserialization make the Symfony side stricter, which reduces contract drift for Laravel consumers.

Testing pattern. Add feature tests for:

• missing required header
• malformed header value
• optional header omitted
• query parameter deserialized into the expected DTO type
• invalid parameter type produces a validation error rather than a 500

Gotchas and Tips

• Laravel is not a supported host out of the box. There is no Laravel service provider or auto-discovery. Do not expect php artisan integration. Use the bundle in Symfony or reuse its validation/deserialization approach manually.
• Header validation depends on the spec. If a header is not declared in the OpenAPI document, the validator cannot enforce it. Keep spec and code in sync.
• Header names are case-insensitive at HTTP level but configuration may not be. Test X-Tenant-Id versus x-tenant-id and document the canonical form.
• Optional versus required headers. A missing optional header should not fail validation. Check that nullable/default handling matches your DTO constructor.
• Deserialization is not validation by itself. Deserializing "abc" into an int property may coerce or fail depending on the serializer. Validate after deserialization and return a controlled 400/422 response.
• Constructor requirements matter. DTOs with required constructor arguments and no defaults are brittle when optional parameters are omitted. Prefer defaults or nullable properties for optional inputs.
• Date, enum, and array parameters are common failure points. Test formats explicitly, especially comma-separated arrays and RFC 3339 dates.
• Cache the spec in production. Parsing and validating OpenAPI documents on every request is wasteful. Warm caches during deploy and clear them on spec changes.
• Debug validation failures by logging the resolved parameter map and the validation error list. Avoid exposing raw spec internals to API clients.
• Extension points: use custom denormalizers or validators for domain-specific parameter formats, and keep bundle-specific logic behind your own adapter if you may move between Laravel and Symfony.
• 3.1.0 is a minor release with no breaking changes or deprecations. The two additions are additive. The main upgrade risk is behavioral: endpoints that previously accepted undeclared or loosely typed headers/parameters may now fail validation if you enable the new checks.