- How do I install wotz/laravel-swagger-ui in a Laravel application?
- Install it with Composer using composer require wotz/laravel-swagger-ui. Then run php artisan swagger-ui:install, which publishes the config file and the SwaggerUiServiceProvider. After that, place your OpenAPI v3 JSON or YAML document in resources/swagger and visit /swagger. The whole setup usually takes well under an hour if a valid spec already exists.
- Does wotz/laravel-swagger-ui support Swagger 2.0 or only OpenAPI v3?
- It renders OpenAPI v3 documents only, in either JSON or YAML format. Swagger 2.0 specs, such as those produced by older darkaonline/l5-swagger setups, must be converted to OpenAPI 3 before the UI will work. It consumes the spec artifact and does not generate or validate it for you.
- How do I restrict access to /swagger so it is not public in production?
- The UI is only reachable in the local environment by default. For anything else you edit the gate method in app/Providers/SwaggerUiServiceProvider.php, which defines the viewSwaggerUI ability, and return your own authorization logic such as an email allowlist or a policy check. The same gate protects both the Swagger UI page and the raw OpenAPI file, so a permissive gate publishes your full endpoint inventory.
- Can wotz/laravel-swagger-ui serve multiple API versions at once?
- Yes. The published config/swagger-ui.php file has a versions array where you map a version key to a spec path, for example 'v1' => resource_path('swagger/openapi.json'). Each entry gets its own UI endpoint under the configured path, which is handy when you ship v1 and v2 APIs concurrently. The base path itself is configurable through the path key, which defaults to swagger.
- Why does Swagger UI's Try it out button call localhost instead of my real API URL?
- The package rewrites the servers and OAuth endpoints in the spec to the active application environment and base URL, so an incorrect APP_URL is the usual culprit. Behind proxies or load balancers you also need correct forwarded-header handling, otherwise the rewrite produces localhost. The docs can look fine while requests fail, so verify the generated servers entry after deployment.
- Which PHP and Laravel versions does wotz/laravel-swagger-ui require?
- Version 2.x requires PHP 8.3 or newer and targets Laravel 11, 12, and 13, with Laravel 13 support arriving in 2.1.0. The 2.0.0 release dropped PHP 8.1 and 8.2 along with Laravel 9 and 10, so older applications need to stay on an earlier major. Each new Laravel major has tended to trigger a breaking or near-breaking release, so plan for a recurring upgrade step rather than a one-time install.
- How do I configure OAuth2 in the Swagger UI?
- OAuth2 settings such as the authorization and token URLs plus client_id and client_secret are injected into the UI through the package configuration file. Note that those values are embedded into the browser page for Swagger UI prefill, so they are visible to anyone who can load the UI. Keep the gate strict anywhere other than local, and prefer public or development clients over confidential credentials.
- Can I point the package at a remote OpenAPI file instead of a local one?
- Yes. Rather than a local path inside resources/swagger, you can supply a URL in the versions config and the UI will load the spec from there. This is useful when your spec is published as a build artifact by CI or hosted on a separate documentation service. The package only proxies and renders the document, so no generation step is involved either way.
- How does wotz/laravel-swagger-ui compare to darkaonline/l5-swagger, and how hard is migration?
- Both expose an OpenAPI document through Swagger UI inside a Laravel app, but this package is a thin, single-purpose add-on: a service provider, a route, and a Blade view, with no Node build step and no external service. Migration is mostly a matter of converting any Swagger 2.0 spec to OpenAPI 3, republishing the config, and rewriting the gate to match your identity model. If you already generate specs with Scribe or Scramble, this package composes with those tools instead of competing with them.
- Is wotz/laravel-swagger-ui safe for production, and what are the maintenance risks?
- It is a thin static-asset and spec-rendering layer with no persistence, so the runtime risk is mostly exposure: the gate guards both the UI and the OpenAPI file, and OAuth client values sit in the browser page. Governance is the bigger concern, since the project is a single-maintainer line that migrated from the NextApps namespace to Wotz at 1.0.0, with zero dependents at the current major. Version 2.0.0 also introduced an opt-in MCP server that exposes your API surface to LLM clients, which expands the trust boundary considerably and should be treated as a separate, deliberate decision. The MIT license means you can fork and patch, so pin the version and keep that option open.