Api Doc Bundle Laravel Package

Getting Started

Read this before anything else: nayzo/api-doc-bundle is a Symfony bundle, not a Laravel package — despite the way it's often listed. It's a downstream fork of nelmio/api-doc-bundle. If your project is Laravel, composer require will pull it in but you cannot wire it up: it depends on Symfony bundle registration, DI container compilation, and the event dispatcher. There's no ServiceProvider shim that will make it work. Skip to the "If you're on Laravel" paragraph below.

If you're on Symfony and want to evaluate, treat upstream Nelmio's documentation as your primary reference and this repo's README.md as a delta — the fork exists to improve on Nelmio's presentation, not to replace its data model. Read the README first, then peek in Resources/ (or examples/) for the value-added templates and sample controllers, then go back to Nelmio docs for anything about areas, models, and Swagger UI.

Minimal steps (Symfony):

1. composer require nayzo/api-doc-bundle.
2. Immediately run composer show nelmio/api-doc-bundle — the resolved version dictates everything downstream. Note it and pin it.
3. Register the bundle in config/bundles.php. Confirm the FQCN from src/ in the repo before editing; a typo here surfaces as a "bundle not found" at cache warmup, not at the line you edited.
4. Import the bundle's route file in config/routes/ — typically one YAML line mounting Swagger UI at /api/doc. Import it in dev.yaml/staging.yaml first, not prod.
5. Create config/packages/<bundle_key>.yaml with at least areas.default.path_patterns: ['^/api']. Everything else has defaults.
6. Open /api/doc in dev. If the spec is empty, your path_patterns are wrong — the bundle is fine.

First real use case: annotate one controller action with the doc attribute/annotation (whichever the fork ships), declare one request body and one response model, reload /api/doc, and confirm it appears with schemas. That annotate → reload → inspect loop is the whole product. Do it on one endpoint before touching anything else.

If you're on Laravel (likely, given the framing), stop and use a Laravel-native tool instead: Scramble (zero-annotation introspection, attribute-driven OpenAPI 3), L5-Swagger (darkaonline/l5-swagger, swagger-php based), or Scribe (human-readable HTML + Postman/OpenAPI export). All are maintained, all compose with Laravel's service provider model, none require a port.

Implementation Patterns

Annotate-then-generate is the whole workflow. The generator walks routes and controllers at build time; your source of truth is docblocks or PHP 8 attributes sitting on controller actions. Pick one style (attributes are the forward path; annotations are legacy) and enforce it in review, otherwise you get a mixed-style spec that's harder to diff.

Use areas to slice the API. Nelmio's areas mechanism is what makes this usable at scale — define one area per API version or per consumer-facing surface (areas.public, areas.partner, areas.internal) with distinct path_patterns. This is how you avoid publishing internal admin endpoints on the partner doc.

Wire doc generation into CI as a checked artifact. Generate the OpenAPI spec in a docs:generate (or equivalent) step and commit the output, or diff it against the previous build and fail on drift. This turns "did we forget to annotate?" into a PR-time question instead of a 5pm-release surprise.

Model references keep schemas honest. For request/response bodies, reference classes/entities rather than hand-writing schemas — Nelmio introspects the class and derives the schema. Hand-written schemas drift silently; introspected ones fail loudly when the model changes, which is what you want.

Customize via template overrides, not by forking the UI. The description advertises theme customization. Do it through Twig template overrides in your app (templates/bundles/NayzoApiDocBundle/...) so you stay upgrade-compatible. If the template you need isn't exposed, that's a fork liability cost, not a feature request.

Integrate with auth and gateway flows. Document security schemes once (Bearer, OAuth2, API key) at the area level and reference them per-operation. If the spec is consumed by a gateway (Kong, AWS API Gateway) or SDK generator, verify the emitted spec is OpenAPI 3.x and validates against openapi-generator-cli — this is a stronger acceptance test than anything visual.

Migrate legacy controllers in reverse-consumption order. Retrofit annotations onto the highest-traffic or externally-consumed endpoints first; leave internal admin endpoints annotated last. Adoption cost per endpoint is real and linear.

Gotchas and Tips

• Stack mismatch is the #1 trap. If you're a Laravel shop and someone has listed this as a "PHP/Laravel" docs tool, that's wrong. The bundle requires Symfony's bundle system. There is no shim, no port, and no plan to build one at 3 stars / 0 dependents. Don't burn a sprint discovering this.
• Version lock to Nelmio. Because this is a fork that enhances Nelmio internals, a routine nelmio/api-doc-bundle patch bump can break your build silently. Pin exact versions in composer.json for symfony/*, nelmio/api-doc-bundle, swagger-php, and PHP. Assume no semver guarantee across Nelmio minors.
• Cache warmup is your first failure surface. Symfony DI compile failures from this bundle surface at cache:clear / cache:warmup — not at request time. If CI's composer install && cache:warmup breaks after a dependency bump, this bundle is a prime suspect. bin/console debug:container Nayzo... and bin/console debug:router (to confirm the doc route is mounted) are your first debug steps.
• Empty spec ≠ broken bundle. An empty /api/doc almost always means path_patterns in the area config doesn't match your actual route prefix. Check bin/console debug:router for what the paths actually look like.
• Annotations-only forks are a dead end. If this fork still reads docblock annotations and hasn't been updated for PHP 8 attributes, it will break on PHP 8.4+/Symfony 7 where annotation readers have been removed. Check for Attribute-based parsing before committing; if absent, treat this as an unmaintained fork.
• Don't expose /api/doc in production unless you deliberately want a public doc surface. Import the route file in config/routes/dev.yaml (and staging.yaml if applicable), full stop. A misconfigured prod doc mount has leaked internal endpoints before in more projects than anyone admits.
• Silent drift is the highest-severity failure. If generation succeeds but the emitted contract no longer matches what the code actually does, downstream gateway configs and generated SDKs break with no warning. This is why you add a CI spec diff (see Implementation Patterns) — it converts a silent failure into a build failure.
• Fork decay is real and undocumented. With 3 stars and 0 dependents, you have no community CVE response, no bug-discovery pressure, and no validation of the Symfony upgrade path. Budget explicit ownership — rebasing against upstream Nelmio, security patching symfony/* and swagger-php, and PHP-version upgrades — or expect bitrot within a couple of Symfony minor cycles.
• Look at upstream before committing. If the specific gap you're closing is presentational (grouping, auth flow clarity, response examples), try the same override as a local Twig template against upstream nelmio/api-doc-bundle first. That's a days-long task with zero fork liability, and it's frequently sufficient. Only adopt this fork outright if the diff proves large enough that reimplementation exceeds a sprint — and even then, vendor it at a pinned version with a named owner.