Laravel Swagger Laravel Package

Product Decisions This Supports

• API documentation as a build artifact, not a manual deliverable. This package generates OpenAPI specs from Laravel route/controller definitions. The 3.3 release strengthens that premise: invokable controller support (#159, #176) and aligning SwaggerService/SwaggerSpecValidator with OpenAPI 3.0 (#203) mean fewer hand-written YAML files and fewer "docs drifted from code" incidents. PM decision enabled: stop budgeting manual API doc maintenance; budget review time on generated diffs instead.
• Partner/consumer integration timelines. OpenAPI 3.0 alignment is the gate for downstream tooling — client SDK generation, Postman/Insomnia imports, API gateway configs, contract testing. If your roadmap includes external API consumers or a developer portal, 3.3 moves you from "docs exist" to "docs are machine-consumable."
• Query-parameter contract accuracy for filtered list endpoints. Expanding with[] and with_count[] into separate, documented query params per relation (#198) directly improves the quality of the most-used endpoints in most Laravel APIs (Spatie Query Builder style includes). This is a consumer-facing correctness fix, not cosmetics — it reduces integration support tickets and wrong assumptions about eager-loading semantics.
• Framework upgrade roadmap confidence. Explicit PHP 8.4 test coverage (#175) and a CI matrix across supported Laravel/PHP versions (#196) are the signal you need when deciding when to schedule a PHP 8.4 bump. PM decision enabled: sequence the runtime upgrade without waiting on a docs-tooling blocker.
• Build vs. buy. Choosing to maintain in-house doc generation is now harder to justify: 3.3 closes coverage gaps (invokable controllers, DI-bound contracts), fixes versioning documentation (#189), and hardens the error page (#164/#174/#185/#186/#191 — trace formatting, font size, no type key) so the debug surface is presentable in non-prod environments shared with stakeholders.
• Operational risk reduction for parallel test suites. The mock parallel-testing token work (#170) plus the local driver fix (#187) and the empty temp_documentation.json production-data fix (#177) address the failure classes that make doc generation flaky in CI — the difference between "docs pipeline is trusted" and "someone regenerates them before a release."

When to Consider This Package

Adopt when:

• You have a Laravel HTTP API with controllers/routes as the source of truth and want OpenAPI output without maintaining YAML by hand.
• Your consumers need machine-readable specs (SDK generation, gateway import, contract tests) — 3.3's OpenAPI 3.0 alignment is the relevant threshold.
• You rely on relation includes/filters (with[], with_count[]) and want those documented per-relation.
• You use invokable/single-action controllers, including those resolved through container bindings to contracts — historically a blind spot, now covered.
• You run docs generation in CI across a version matrix and need parallel-test safety.

Look elsewhere or defer when:

• You need a design-first workflow (spec authored by hand, code validated against it). This package is generation-oriented; design-first governance is a different tool category.
• You require a guaranteed-stability contract. 3.3 includes a self-revert of the PHPUnit 12 upgrade (#172 → #173). If your test stack is already on PHPUnit 12, verify compatibility before adopting; treat PHPUnit-major parity as a moving target.
• You need vendor-backed SLAs. This is a community package with a growing contributor base; four first-time contributors in one release is healthy but signals bus-factor and review-depth variance.
• Your API surface is dominated by non-controller entry points (GraphQL, event-driven, gRPC) — out of scope.
• You are on an unsupported Laravel/PHP combination. The new CI matrix is the authoritative support statement; check it before planning an upgrade.

Before committing: validate the generated spec against your own OpenAPI 3.0 linter, and confirm the error-page changes are acceptable in any shared non-production environment (they alter what stakeholders see on a 500).

How to Pitch It (Stakeholders)

For executives (one paragraph): We currently spend engineering time keeping API documentation in sync with the code, and out-of-sync docs create support load and slow down partner integrations. This package generates the API specification directly from our Laravel code, and release 3.3 makes that output machine-consumable (OpenAPI 3.0 alignment), covers a broader set of controller patterns, and documents our relation-based query parameters properly. It also adds PHP 8.4 test coverage, which de-risks our planned runtime upgrade. Net effect: lower documentation cost, faster and more accurate external integrations, and one fewer blocker on the platform upgrade path — without adding a vendor contract.

For engineering: 3.3 is a coverage-and-correctness release, not a rewrite. Wins: invokable controllers documented, DI-by-contract resolution fixed, OpenAPI 3.0 alignment in the validator, with[]/with_count[] expanded into discrete documented query params, CI across all supported version combos, PHP 8.4 in the matrix, and a set of fixes targeting real CI pain (parallel-test token mocking, local driver, empty temp JSON clobbering production data, versioning docs). Formatting/consistency improved via a newly added Laravel Pint config.

Caveats to state up front: PHPUnit 12 support was merged and then reverted in the same release — pin your test tooling and confirm compatibility rather than assuming parity. This is a community-maintained package; we should pin a version, run our own spec validation in CI, and keep the generation step behind a check so an upstream regression cannot silently ship a broken contract. Recommend adopting 3.3 behind a pinned constraint with a spec-lint gate, then evaluating removal of any in-house doc tooling in the following cycle.