Api Doc Bundle Laravel Package

Product Decisions This Supports

• API documentation as a launch gate, not an afterthought. If an API is a customer-facing or partner-facing deliverable, "is the reference doc accurate?" becomes an acceptance criterion. This bundle makes the OpenAPI spec a build artifact generated from the same PHP attributes that define the endpoints, so the doc can be reviewed in a PR rather than written by hand after the fact. That directly de-risks external API launches, partner integrations, and sales-led "do you have an API?" conversations.
• Build vs. buy for the developer-portal surface. The bundle ships Swagger UI, ReDoc, Stoplight Elements, and Scalar as built-in render targets. That means the "we need a docs site" request can often be satisfied with near-zero incremental spend — no ReadMe, Stoplight platform, or Bump.sh subscription for the base case. The decision becomes "do we need a portal (auth, analytics, changelogs, multi-product) or just a reference?" and this package covers the latter for free.
• Make the OpenAPI spec a platform contract. The generated openapi.json is the input to SDK generation, Postman collections, mock servers, and contract tests. Adopting this is really a decision to have one machine-readable source of truth that downstream teams can consume, and it unlocks roadmap items (client SDKs, sandbox) that would otherwise require bespoke work.
• Docs coverage as a measurable metric. Because spec generation is deterministic per route, you can track "percentage of endpoints with a described response and at least one error case" as a quality KPI and put it on a dashboard. That turns "our docs are bad" from a vibe into a number with an owner.
• Scoping/segmentation decisions. The bundle's "areas" concept (splitting the spec by path pattern or attribute) lets you decide product-wise whether public, partner, and internal APIs get one doc or three — which is really a decision about who you expose what to.
• Security posture visibility. Auto-deriving security schemes from #[IsGranted] means the published spec reflects which endpoints are authenticated. Useful for security reviews and for answering enterprise prospect questionnaires ("which endpoints require OAuth?") without an engineer doing an audit.
• Framework/version roadmap inputs. Version 5.x requires PHP 8.1+ and Symfony 6.4+, dropped annotation support in favor of attributes, and supports FrankenPHP worker mode and Symfony's type-info. Adopting it is a soft commitment to staying on modern Symfony/PHP — worth sequencing against your platform upgrade roadmap.
• Not a decision this supports: runtime request/response validation, rate limiting, or enforcing that the implementation matches the spec. It documents; it does not police. If you need drift detection you need something else in addition.

When to Consider This Package

Adopt when:

• The stack is Symfony 6.4+ on PHP 8.1+. This is a Symfony bundle first and foremost — it will not drop into a Laravel, Slim, or vanilla-PHP application without meaningful glue work. Treat "Laravel/PHP package" framing as a red flag and verify the framework before anything else.
• You already use Symfony Serializer or JMS Serializer for models, or are willing to — the bundle's model describers are where most of its value (accurate schemas with zero duplication) comes from.
• You want attribute-driven, in-code documentation that lives next to the controller and is reviewed in the same PR, rather than a separate spec file or wiki that rots.
• You need multiple output UIs or a spec-only mode — e.g., render Swagger UI internally but publish the raw OpenAPI JSON to partners.
• You need multiple audience-specific docs (public vs. internal) from one codebase via areas.
• You're on or planning FrankenPHP / long-running workers — 5.11.1 explicitly hardened generation for that mode.

Look elsewhere when:

• The application is Laravel. Use dedoc/scramble (attribute/reflection-driven, zero-config) or darkaonline/l5-swagger (swagger-php based) instead. Choosing this package for a Laravel app means paying an integration tax forever.
• You're on API Platform — OpenAPI generation is built in; adding this is redundant.
• You're still on PHP annotations or Symfony < 6.4 — 5.x removed annotation support; you'd be pinned to an older major with a migration debt clock running.
• You need runtime validation, contract testing, or mocking — pair the spec with Schemathesis, Dredd, or Prism; this package does not do enforcement.
• You need a full developer portal (hosted docs, API keys, usage analytics, changelog, multi-product navigation). The bundle generates the reference; a portal is a separate buy/build decision.
• Your team won't maintain the attributes. A generator with no discipline produces a confidently wrong spec, which is worse than no spec — plan for a review checklist or CI check on the spec diff.

How to Pitch It (Stakeholders)

To executives: This is a free, MIT-licensed, actively maintained component that turns our API code into published API documentation automatically. It removes a recurring manual cost and a recurring accuracy problem — docs generated from code can't silently drift the way a wiki can. It also produces a standard OpenAPI file, which is the thing enterprise buyers, partner integrators, and SDK generators all ask for. Cost is engineering time, not license spend; the realistic alternative is either a paid docs platform or an engineer hand-writing docs quarterly. The strategic value is speed-to-integration for anyone consuming our API.

To engineering: It's the de-facto standard for Symfony API docs and has been for over a decade — 2.4k stars, steady releases through 2026, MIT, documented upgrade paths across every major version. It reads PHP 8 attributes and Symfony Serializer metadata, so schemas come free from your existing models rather than being re-declared. You get Swagger UI / ReDoc / Stoplight / Scalar out of the box, area-based splitting for public vs. internal specs, operation-ID generation control, and #[IsGranted]-derived security schemes. It runs under FrankenPHP worker mode and supports Symfony's type-info. The real cost is discipline: attributes must be updated with the endpoint, and 5.x means PHP 8.1+/Symfony 6.4+ and no going back to annotations. Flag clearly: this is a Symfony bundle — if any of our services are Laravel, we standardize on a different tool there, not this one.