L5 Swagger Laravel Package

Product Decisions This Supports

• Public vs. internal API surface. L5-Swagger turns your Laravel routes into a browsable, interactive reference. That makes "do we expose this endpoint to partners?" a decision you can validate cheaply — publish a spec to a staging UI, watch what integrators actually ask about, then commit to a public contract.
• Build vs. buy for developer documentation. The realistic alternative is a paid portal (ReadMe, Stoplight, SwaggerHub) or hand-maintained Markdown. This package is the "buy nothing, wrap the standard" option: MIT-licensed, ~3k stars, output is plain OpenAPI, so the artifact outlives the tool.
• Contract-first vs. code-first. Because it wraps swagger-php, the spec lives as PHP attributes next to the controllers. That couples docs to implementation — great for velocity, worse for designing an API before building it. Use it to decide where in the lifecycle your team writes specs.
• Onboarding and support-cost reduction. Try-it-out requests in Swagger UI (with Passport/Sanctum auth schemes wired in) cut the "how do I authenticate?" ticket class and shorten partner integration time — a measurable support-ops lever, not just a docs nicety.
• API versioning and deprecation policy. A generated, diffable spec makes breaking changes visible in code review. That supports a real deprecation standard instead of ad-hoc /v2 decisions.
• Roadmap sequencing for platform work. If the roadmap includes SDKs, partner portals, or gateway-level governance, OpenAPI is the prerequisite artifact. Adopting now buys optionality later at near-zero cost.

When to Consider This Package

Adopt when:

• Your backend is Laravel ≥ 11 on PHP ≥ 8.2 (v9+ dropped older support; v11 tracks the current Laravel major).
• You want zero new infrastructure — a config file, an artisan command, and a route serve the UI.
• A small team owns the API and can afford annotation upkeep in exchange for docs that never drift from code.
• You need authenticated try-it-out (Passport/Sanctum) without building a custom console.

Look elsewhere when:

• You're polyglot or multi-service. Use a spec-first platform (Redocly, Stoplight, SwaggerHub) that isn't tied to one framework.
• You want docs with no annotations. dedoc/scramble-style route introspection is a better fit if the team won't maintain attributes.
• You need a governed developer portal: analytics, API keys, changelogs, multi-version hosting, SDK generation at scale. This package serves a UI; it is not a portal.
• Design-first workflow with mocking and review gates is a hard requirement.
• Non-Laravel stack, or a legacy Laravel/PHP version you can't upgrade.

Risk checks before committing: single-maintainer concentration (bus factor), a major-version cadence that tracks Laravel majors and requires migration work (the v10 removal of Doctrine annotations is precedent), and a history of security patches in the UI assets — pin versions and track advisories. Note the "0 dependents" figure is a data artifact, not a signal; the download badge tells the real adoption story.

How to Pitch It (Stakeholders)

To executives: This is a free, MIT-licensed Laravel package that publishes a live, interactive API reference from the code we already write. It replaces a five-figure developer-portal contract for our current stage and shrinks partner onboarding and API support load. The output is standard OpenAPI, so we are not locked in — if we outgrow it, the spec moves with us.

To engineering: It's a thin wrapper over swagger-php and swagger-ui — no custom spec dialect, no runtime dependency in the request path. Spec generation is a build-time artisan command; the UI is a single route you can restrict to non-production. Configuration is one published config file. Cost is annotation discipline in controllers; benefit is a spec that can't silently drift, plus auth-aware try-it-out. Upgrades are small, versioned, and tied to Laravel majors — budget a short maintenance window per Laravel upgrade.

To security/ops: No external service, no data leaves the stack. Gate the docs route by environment, pin the package version, and monitor the changelog — the project has responded quickly to path-traversal and UI CVEs historically.