Api Doc Bundle Laravel Package

Technical Evaluation

Architecture fit. The first finding a TPM must escalate is categorical: nelmio/api-doc-bundle is a Symfony bundle, not a Laravel package. It boots via a Symfony DI extension, registers tagged services (PropertyDescriberInterface, model describers, area describers), and hooks the kernel — there is no service provider, no facade, no Laravel package discovery. In a Laravel codebase it will not install or boot cleanly. If the target stack is Laravel, the correct architectural comparison set is dedoc/scramble (runtime route introspection) or darkaonline/l5-swagger (swagger-php wrapper), and this package should be rejected on fit rather than on quality. If the target is Symfony 6.4+/7.x with PHP 8.1+, this is close to the reference implementation for code-first OpenAPI generation from PHP 8 attributes.

Integration feasibility. Assuming Symfony, feasibility is high: one composer require, a config/packages/nelmio_api_doc.yaml block defining areas, and an #[OA\...]/#[Model] annotation pass over controllers and DTOs. The bundle is deliberately thin on opinion — it produces the OpenAPI document and serves a bundled UI (Swagger UI, ReDoc, Stoplight Elements, or Scalar as of 5.10). The real effort is not installation, it is the annotation backlog across every endpoint and model, plus configuration of areas if the API surface is multi-version or multi-audience.

Technical risk.

• Framework mismatch (high, if Laravel): decisive and non-mitigable short of adopting Symfony. Do not accept "it's PHP so it probably works."
• Documentation drift (medium): generation is attribute-driven, not runtime-introspected. The published contract is only as true as the attributes, and nothing fails if a controller changes and the attribute does not.
• Version coupling (medium): 5.x requires PHP 8.1+ and Symfony 6.4+, with the 7.x floor moved to 7.1 in 4.34.0. That tightens the framework upgrade calendar for the whole application.
• Deprecation churn (low–medium): the 5.x line carries an active deprecation schedule (with_annotation → with_attribute, Areas array-key shape, Model::$options nullability). Manageable only with a CI deprecation gate.
• Metadata anomaly (validation gap): the record shows 2,378 stars but 0 dependents, and a last-release date of 2026-10-30. Both should be re-verified against Packagist and the GitHub releases feed before the number is used in any decision document.

Key questions.

1. Is our API codebase Laravel, Symfony, or mixed? (This alone gates the decision.)
2. Contract-first or code-first — and does the contract need to be authoritative for downstream consumers, SDK generation, or a gateway?
3. Do we require the spec to reflect runtime route/validation state, or is a curated, attribute-maintained spec acceptable?
4. How many API versions/audiences must be documented concurrently (drives areas configuration complexity)?
5. Who owns the spec as an artifact — is it reviewed like code, or generated ad hoc?
6. Are we on FrankenPHP/Octane-style long-running workers, where doc-generation state isolation matters?

Integration Approach

Stack fit. Symfony 6.4/7.1+, PHP 8.1+, Symfony Serializer or JMS Serializer for model description, Doctrine entities or DTOs as schemas, zircote/swagger-php ^5.7.8/^6.0 underneath. Optional integration points worth planning for: #[IsGranted]-derived security schemes (5.2.0), MapQueryParameter with regex conversion to ECMA-262 (4.38.2), MapUploadedFile (4.38.0), TranslatableInterface (5.3.0), and symfony/type-info (4.35.0). If any of these appear in our controllers, they are cheap wins; if our auth is a custom middleware rather than Symfony security, the security-scheme automation will not apply and must be hand-declared.

Migration path. Two distinct migrations, budget them separately:

• 4.x → 5.x (if we have existing usage): annotations are removed in favor of attributes; requires PHP 8.1 and Symfony 6.4. This is a mechanical but broad rewrite across every docblock — estimate per-endpoint, not per-file.
• Swagger 2.0 → OpenAPI 3.0 (v3 → v4+): a spec-level break that propagates to every downstream consumer (mock servers, client generators, gateway importers). Sequence consumer readiness before the library upgrade.

Compatibility. Pin the bundle minor and let Composer resolve; the 5.x line ships frequently. Watch three seams: the Symfony minor floor, the swagger-php major, and the bundled front-end asset versions (Swagger UI/ReDoc/Scalar/Stoplight are vendored into /utils and bumped almost every release — this shows up as lockfile and static-asset churn, not PHP risk).

Sequencing.

1. Confirm framework and, if Symfony, confirm version floor.
2. Spike: install, one area, one controller, one #[Model] — validate generated JSON against an OpenAPI 3 validator.
3. Decide UI and place the docs route behind auth in non-local environments.
4. Instrument the highest-value endpoints (public/partner-facing) first; internal endpoints later.
5. Add CI: regenerate the spec on every PR, fail on diff (drift gate) and on deprecations.
6. Establish areas for each API version/audience.
7. Publish the spec as a versioned artifact to consumers; only then deprecate any hand-maintained spec.

Operational Impact

Maintenance. Healthy: MIT, active CI with Codecov, frequent patch/minor releases, corporate sponsorship, and explicit upgrade guides per major. Vendor risk is low; the ongoing cost is annotation upkeep — every endpoint change now has a documentation obligation, and that obligation is unenforced by the framework. Budget it as a standing tax, not a one-off project.

Support. Community-only. Issues are handled on GitHub with no SLA; the authoritative documentation lives on symfony.com rather than the repo. We need an internal owner who understands describers and areas, because escalations will land on us.

Scaling. Generation cost scales with model-graph size and number of areas — expect slow cold generation on large entities, mitigated by caching/warmup. The served UI is static assets, effectively free at runtime but a public information-disclosure surface: gate it. 5.11.1 specifically hardened generation for FrankenPHP and long-running workers, so state bleed across requests is a known-and-addressed class of bug — pin at or above that.

Failure modes to instrument for. (a) Silent drift between attributes and actual behavior — mitigated by the CI diff gate but not eliminated; (b) schema deduplication collisions across namespaces — FQCN keying landed in 5.10, older pins can merge distinct models; (c) nullable/oneOf mis-wrapping in the JMS describer (5.10 fix); (d) root-level vendor extensions being dropped (5.10.2); (e) generation exceptions taking out the docs route or, worse, CI; (f) framework upgrade blocked by the bundle's Symfony floor.

Ramp-up. For a Symfony-fluent engineer, one to two days to first productive spec, roughly a week to own areas, describers, and security schemes. Non-trivial prerequisite knowledge: OpenAPI 3.0 semantics and Symfony DI/tagged services. For a Laravel-only team, ramp-up is not the issue — the framework mismatch is, and time spent here is better redirected to dedoc/scramble.

Recommendation. Adopt if and only if the API is Symfony 6.4+/PHP 8.1+. Reject for Laravel on architecture fit, not on package quality. Either way, make the CI drift gate and docs-route authentication part of the initial scope rather than a follow-up — they are the difference between a documentation system and a stale liability.