Laravel Swagger Ui Laravel Package

Product Decisions This Supports

• Public/partner API launch readiness. If the roadmap includes exposing an API to third parties, this package converts an existing OpenAPI file into an interactive, try-it-out reference in hours rather than weeks. It is a distribution layer for docs, not a docs platform.
• Build vs. buy for the developer portal. Replaces a bespoke "docs page" ticket (custom Blade view + JS bundle + auth wiring + env-aware base URL) with a config file and one Artisan command. The build option is 3–10 engineer-days plus permanent maintenance for every Laravel major; this is ~1 day including review.
• Roadmap scoping: "do we need a docs product?" Use it as the cheap baseline. Adopt it for internal/staging docs and defer spend on ReadMe/Stoplight/Scalar until you have a concrete unmet need (guides, changelogs, multi-service catalog, customer analytics, hosted sandbox).
• API versioning strategy. The versions config maps multiple spec files to multiple UI routes (/swagger/v1, /swagger/v2), which makes a "sunset v1, promote v2" rollout a config change rather than a docs project.
• Access-control and security posture decisions. The gate (viewSwaggerUI) plus local-only default and pluggable middleware is the decision point for "who sees our API surface" — internal-only vs. authenticated partners vs. fully public. Worth an explicit product call, not a default.
• Try-it-out / demo enablement. OAuth2 client ID/secret injection and env-aware base URLs mean sales engineers, solutions architects, and support can reproduce a customer's exact call against the right environment. That is a support-ticket-deflection lever, not just a dev convenience.
• Agent/AI-readiness exploration (v2.0+). The optional MCP server exposes spec metadata to LLM tooling. Treat as a bet to prototype, not a commitment — it requires laravel/mcp and its own auth (Passport OAuth routes) and has almost no field usage yet.
• Buy-vs-fork risk decision. With ~280 stars, one primary maintainer, and zero dependents, the correct product framing is "thin, MIT-licensed wrapper we can fork in a day," which makes adoption a low-consequence, reversible decision.

When to Consider This Package

Consider it when most of these are true:

• The stack is Laravel 11, 12, or 13 on PHP 8.3/8.4 and you are willing to stay current — this package tracks Laravel majors closely but drops old ones (2.0 removed Laravel 9/10 and PHP 8.1/8.2). Budget a minor upgrade each Laravel cycle.
• You already have an OpenAPI v3 JSON or YAML file. This is a renderer. It does not generate specs from annotations or routes. If you don't have a spec, the real project is spec generation (e.g.,dedoc/scramble, Scribe, or l5-swagger), and this package is only the last mile.
• The UI is for internal, staging, or authenticated-partner audiences. Local-only-by-default plus a gate is a sensible posture; it is not a hardened public-docs CDN.
• You want zero frontend toolchain — no Node build, no separate docs repo or deploy pipeline. Docs ship with the app, versioned in the same PR as the endpoints.
• The spec lives in the repo or at a URL and needs to be environment-aware — auto-rewritten server URL and OAuth endpoints are the package's genuine differentiator over dropping static Swagger UI assets in public/.
• You need multi-version docs or a per-version server URL with variables ({Language}, region), and CSS-level branding is enough customization.

Look elsewhere when:

• You are not on Laravel (Symfony, Node, Go) — use upstream Swagger UI, Redoc, or Scalar directly.
• You need spec authoring, linting, or contract testing in the loop. Pair a generator with this, or pick an opinionated tool that does both.
• Docs are customer-facing at scale — you need guides, quickstarts, search, API keys, usage analytics, and a sandbox. That's a docs product (ReadMe, Stoplight, Mintlify, Redocly), and building it on this is a false economy.
• You need a curated, non-Swagger reading experience. Redoc and Scalar generally read better than Swagger UI for public reference; Swagger UI wins on try-it-out.
• You need long-term vendor-style support, SSO beyond simple gates, or an SLA. One maintainer, no dependents, no commercial backing — acceptable for internal tooling, questionable for a revenue-facing commitment.
• Exposing it publicly without a gate. Verify the middleware and gate config against your threat model before shipping anything beyond local/staging.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can ship interactive, always-current API documentation to partners and internal teams for roughly a day of engineering and $0 in licensing, instead of a multi-week custom build or a recurring docs-platform contract. It's MIT-licensed, integrates natively with our Laravel stack, inherits our existing authentication, and — because it's a thin wrapper around the standard Swagger UI — is replaceable at any time without rewriting anything. The main caveat is that it only displays an API spec; it assumes we already produce one. Recommend approving as a low-risk, reversible enabler for the API roadmap, with adoption deferred to staging/internal first.

For engineering (talking points):

• One composer require plus php artisan swagger-ui:install; publishable config and service provider; UI served at /swagger.
• Config-driven: spec path or external URL, multiple versions, custom path, middleware array, custom CSS, page title, validator URL, server URL + URL variables, modify_file toggle for env-based rewriting.
• Auth is a gate (viewSwaggerUI) — swap in our SSO/email allowlist; non-local access is denied by default.
• No Node/npm, no compiled assets, no separate docs service to deploy or monitor. Docs version with the code.
• Actively maintained through Laravel 13 / PHP 8.4 (2.1.x); semver with a documented changelog; 2.x signals willingness to make breaking-but-clean changes.
• Risks to note: single maintainer, no downstream dependents to signal battle-testing, breaking changes tied to Laravel majors, and the MCP feature pulls in laravel/mcp and Passport OAuth plumbing — treat MCP as experimental.
• Mitigation: the surface area is small and MIT, so forking is cheap; pin a version and add a CI check that the spec file parses.

Ask: Approve a one-sprint spike to deploy behind the existing gate in staging, validate it against the current OpenAPI spec, and return a go/no-go for partner-facing use — with public exposure and MCP explicitly out of scope for this phase.