Swagger Bundle Laravel Package

Getting Started

This bundle plugs into Symfony's HTTP kernel and compares requests/responses against a Swagger 2.0 document. It is old (last release Feb 2017), so start by confirming compatibility before investing time.

1. Check versions first. Inspect composer.json constraints: expect PHP 5.6/7.0–7.1 and Symfony 2.8/3.x. On Symfony 4+ or PHP 8 you will need to fork or pin aggressively. Run composer require nicofuma/swagger-bundle:^1.0 --dev in a throwaway branch and let Composer tell you what it can resolve.
2. Register the bundle. Symfony 2/3: add it to AppKernel (new Nicofuma\SwaggerBundle\NicofumaSwaggerBundle()). Symfony 4+: add to config/bundles.php if the class loads, otherwise you are in fork territory.
3. Point it at a spec. Publish/inspect the bundle config (app/config/config.yml or config/packages/) and set the path to your swagger.json/swagger.yaml (usually one of documentation, spec, or file keys depending on the version). Keep the spec under %kernel.project_dir%.
4. Enable only in dev/test. This is a contract-checking tool, not production middleware. Gate the bundle config per environment so you don't pay validation cost on live traffic.
5. First use case: add a single documented endpoint (e.g. GET /api/ping), boot the app in test, hit it with the Symfony test client, and confirm the bundle raises an exception or logs when you deliberately return a malformed body. That proves the wiring end-to-end before you widen coverage.

Where to look first: the bundle's DependencyInjection/Configuration.php (all real options live there, not always in the README), then its event subscriber(s) to see which kernel events are hooked and what exception type is thrown on failure.

Implementation Patterns

Contract testing in CI (primary pattern). The most valuable use is running functional tests with the listener enabled in test, so every KernelBrowser request is validated against the spec. Combine with symfony/phpunit-bridge; a schema violation then fails the build rather than a downstream consumer.

Response-only validation for legacy request handling. Old APIs rarely accept perfectly spec-shaped input (form encodings, trailing slashes, vendor headers). Configure request validation off for handlers you can't change and keep response validation on — it catches the drift that actually breaks clients.

Annotation-driven spec generation. The bundle ecosystem sits on swagger-php annotations. Keep the annotations on controller methods and generate the spec as a build step (a small console command or swagger-php CLI run), then feed the generated file to the bundle. This keeps spec and code co-located and makes drift visible in diffs.

Path whitelisting. Large apps will have endpoints you don't want validated (health checks, webhooks, file uploads). Use the bundle's path/route filtering config rather than disabling globally; validate the API surface incrementally, one resource at a time.

Environment-scoped listener. If the bundle doesn't filter by env itself, wrap or decorate its subscriber with a service that checks %kernel.environment% and returns early. This prevents accidental production overhead if someone merges a bad config.

Custom failure handling. Instead of letting a ResponseValidationException bubble up, register a listener on the bundle's exception/event to convert mismatches into structured log entries (endpoint, JSON pointer, expected vs actual). This turns the bundle into a usable debugging assistant rather than a blunt test failure.

Pair with HTTP fixtures. Store request/response pairs next to the spec and replay them in tests; the bundle validates the response half, the fixtures pin the request half. This catches the gap where requests silently drift but still validate because required fields happen to be present.

Gradual adoption via a proxy. For integration environments, route traffic through a test-only kernel listener that validates and logs without blocking. Sample a percentage of real traffic, fix the biggest offenders, then flip to throwing.

Gotchas and Tips

• Maintenance risk is the dominant gotcha. Eight stars, zero dependents, no release since early 2017. Treat it as glue code you may own: fork it, vendor it, or budget time to replace it. It is not a dependency to put on a critical path.
• Swagger 2.0 only. There is no OpenAPI 3 support. If your spec is openapi: 3.0.x, this bundle will not parse it. league/openapi-psr7-validator or thephpleague/openapi-psr7-validator is the modern replacement; byfareska/php-swagger-test covers the contract-test angle.
• Version pinning traps. Old bundles commonly pin symfony/* to ~2.8|~3.0 and swagger-php to 2.x. Composer will quietly downgrade half your stack if you're not careful — always run installs with --dry-run first and commit the lockfile.
• $ref resolution. Specs with external or fragmented $refs are the most common source of "valid request, spurious failure." Inline the refs at build time or keep everything in one file.
• Format and additionalProperties are strict. Swagger's format: date-time and undeclared properties fail validation even when the client works fine. Decide per-project whether to relax the spec or the validator; don't chase one-off schema tweaks forever.
• Response validation and streams don't mix. Binary/file responses, chunked streams, and 204 No Content frequently trip validators. Exclude those routes.
• Errors can be swallowed. Depending on config, violations may only log. Check the subscriber's behavior early — a green test suite can mean "validation silently off," not "everything passes."
• Performance. Full schema validation on every request is measurable. Never enable on production; if you must sample, do it at the edge, not in the kernel.
• Extension points are thin. Expect to subclass or decorate the request/response listeners for custom behavior; there is no rich plugin system. Keep your customizations in your own bundle so the eventual replacement is a swap, not a rewrite.
• Debugging tip: reduce to a single route and a minimal spec object ({ "type": "object", "properties": { "id": {"type": "integer"} } }) to confirm the pipeline works before blaming your full document. Most failures are spec shape, not bundle bugs.