Laravel Laravel Package

Product Decisions This Supports

• Docs as a shippable feature, not a side project. This package lets a Laravel app serve a Scalar API Reference UI directly from its OpenAPI document — typically a composer require, a config publish, and a route. That turns "we should really document our API" from a multi-sprint initiative into a small, testable deliverable. The PM decision it unlocks is whether to invest in a docs surface at all this quarter, and it lowers the cost of saying yes.
• Build vs. buy for the docs layer. The realistic alternatives are hosted portals (ReadMe, Stoplight, Scalar's own commercial platform, Redocly) or hand-rolling a static site. Self-hosting this package keeps docs inside the existing Laravel deploy, auth, and CI — no new vendor, no separate site to keep in sync. The buy decision remains open later because the artifact is a portable OpenAPI file, not proprietary content.
• OpenAPI-first as the contract. Adopting the package implicitly commits the team to maintaining a spec (openapi.json/yaml) as the source of truth — either hand-authored or generated via tooling like dedoc/scramble or Scribe. That is a real architectural decision: the spec becomes a reviewable artifact in the repo and a prerequisite for SDK generation, contract tests, mock servers, and gateway configuration downstream.
• Replacing an existing reference UI. For teams already on Swagger UI or Redoc inside a Laravel app, this is a like-for-like swap with a materially better reading experience (try-it, modern layout, dark mode, multi-language code samples). Low-risk, high-visibility change — good candidate for a "polish" roadmap item.
• Internal API catalog / platform hygiene. For platform teams with several Laravel services, a consistent embedded reference per service is a cheap way to raise the floor on internal discoverability without standing up a central developer portal.
• Use cases this fits: B2B/partner API products where the reference is customer-facing, internal microservice documentation, and pre-sales/technical-evaluation surfaces where a credible interactive reference shortens integration conversations.

When to Consider This Package

Adopt when most of these are true:

• The product is a Laravel app (or a Laravel service that can own a docs route) — this is not framework-agnostic.
• You already have, or can cheaply generate, a valid OpenAPI 3.x document in the repo. Without that, the package has nothing to render and the real work is spec authoring, not the UI.
• You want the reference co-located with the API — same domain, same auth middleware, same deploy pipeline — rather than on a separate docs subdomain or vendor portal.
• The audience is developers who will actually click "try it", and the API is reachable from the browser (CORS/auth token flow is workable).
• You're comfortable with a small, single-purpose dependency: 77 stars, MIT, unknown/unspecified repository, and a low composite score (~18/100) are maturity signals worth naming. Treat it as a thin renderer you could replace, not load-bearing infrastructure.
• The surface is internal, partner-gated, or reasonably tolerant of a young tool. Keep the spec as the durable asset.

Look elsewhere when:

• You need a full developer portal — versioned docs, custom domains, SEO, search analytics, gated content, changelogs, API keys self-serve. That's a hosted product (ReadMe, Stoplight, Scalar platform), not this.
• You need spec authoring, linting, style governance, or design-first workflows — that's Stoplight/Redocly territory; this package renders, it doesn't govern.
• You need enterprise support, an SLA, or security review of a well-known vendor. A 77-star package with an unclear repository provenance will not clear that bar for a revenue-critical public surface without an internal fork-and-own decision.
• You need SDK generation, mock servers, or contract testing — adjacent tooling, not this package.
• You're not on Laravel, or you'd rather ship a static reference to a CDN than run another route in the app.
• Your API is multi-service and polyglot — a per-framework integration won't scale into a catalog; go to a central portal or a framework-neutral static build.

Practical guardrail: keep the OpenAPI file in the repo and the UI behind config. If the package stalls or is abandoned, swapping the renderer should be an afternoon, not a migration.

How to Pitch It (Stakeholders)

For executives: We can put a credible, interactive API reference in front of customers for a fraction of a sprint, using an MIT-licensed package inside our existing Laravel deployment — no new vendor contract, no new infrastructure, no separate docs site to maintain. Because the underlying artifact is a standard OpenAPI document we own, this is reversible: if it doesn't earn its place, we keep the spec and change the presentation layer. Recommended ask is a timeboxed spike, not a commitment.

For engineering: One dependency, one config file, one route. It renders an OpenAPI spec we already generate with Scramble/Scribe, and replaces Swagger UI with something developers will actually use. It's a thin presentation layer — no runtime coupling, no database changes, no queue or worker footprint. The real prerequisite is treating the spec as a maintained, reviewed artifact, which is worth doing regardless.

Risks to state plainly: It's a small project (77 stars, MIT, limited community) — we should pin the version, avoid forking behavior we depend on, and assume we may own it eventually. Composite maturity score is low. That's acceptable for an internal or partner-facing surface with a clean escape hatch; it's a harder sell for a flagship public developer brand until we've validated it.

Decision requested: Approve a 1–2 day spike to wire it to our existing spec and put it in front of five internal or design-partner developers. Success criteria: spec renders correctly, try-it works against staging, and no new operational burden. Revisit the hosted-portal question only if we need versioning, analytics, or gated access.