- How do I install laravel-stoplight-elements?
- Install it with Composer using composer require juststeveking/laravel-stoplight-elements. Then publish the package config and views, register or configure the docs route, and point the package at your OpenAPI 3.x specification. The package is a thin service provider plus Blade view, so setup is minimal.
- Does this package support Laravel 12?
- Yes. Release 3.0.1 adds Laravel 12.x compatibility via a Laravel Shift pull request, and it is a patch-level, additive release. If your application is pinned to Laravel 10 or 11, the release is not newly actionable and the value is the same as 3.0.0. Expect a maintenance release around future Laravel majors.
- What OpenAPI specification versions can I use?
- The package is intended for OpenAPI 3.x specifications rendered through Stoplight Elements. You configure it to point at your spec, and the Elements web component handles the interactive reference UI in the browser. It does not generate the OpenAPI document for you.
- How do I change the documentation route or use a custom domain?
- The docs route is configurable through the published configuration, and release 3.0.1 adds a custom-domain option from PR #12. Read that pull request before promising a branded public developer portal, because it is worth confirming whether the option changes the asset host, spec URL, route domain constraint, or all three. For most teams, changing the route in config is enough.
- Do I need to publish the config and Blade views?
- You can publish the package config and views, and doing so is the normal way to customize the route, spec location, and presentation. The package is deliberately thin: a service provider mounts Stoplight Elements and serves it through a configurable route and Blade view. If you do not need customization, the defaults may be sufficient.
- Is this a full developer portal or just an API reference?
- It is an API reference renderer, not a narrative developer portal. Stoplight Elements displays your OpenAPI spec interactively, but it does not provide quickstarts, guides, tutorials, or versioned prose documentation. Set expectations deliberately by calling it an API reference rather than the docs.
- What are the production risks of client-side docs rendering?
- Because Stoplight Elements renders in the browser with a JavaScript bundle, failures such as CSP violations, an unreachable asset host, or a 404 on the spec fetch may not appear in server logs like a normal 500. Add an explicit smoke test in CI that loads the docs page and confirms the spec is fetched and rendered. Exposure level also matters: internal, partner-facing, and public docs have different security and infrastructure requirements.
- How actively is laravel-stoplight-elements maintained?
- It has a small footprint, roughly 44 stars, no published dependents, one primary maintainer, and occasional community pull requests, with no commercial backing. That makes maintainer concentration the dominant risk, but the fork surface is tiny. You can vendor or reimplement it in a sprint if upstream maintenance stalls.
- Can I use this package for internal-only API documentation?
- Yes. The package is a presentation-layer dependency and does not impose persistence, queues, auth model, or domain logic, so it can be mounted for internal use. Whether the docs surface is internal-only, partner-facing, or public determines the real scope, including security review, CDN, DNS, and branding work. Plan the exposure model before launch.
- What alternatives should I consider for Laravel API documentation?
- Alternatives include other OpenAPI renderers such as Swagger UI or Redoc, and Laravel-specific documentation generators such as Scramble or Scribe. Choose based on whether you already maintain an OpenAPI 3.x spec and just need a reference UI, or need generation and narrative docs. This package is a cheap, reversible choice when you want Stoplight Elements with minimal Laravel setup.