Weave Code
Swagger Ui Laravel Package
swagger-api/swagger-ui
Swagger UI renders interactive API documentation from your OpenAPI/Swagger spec. Let developers and consumers explore endpoints, try requests, and see schemas without backend implementation. Available as npm modules (swagger-ui, swagger-ui-dist) and Docker image.
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
Frequently asked questions about Swagger Ui
- How do I integrate Swagger UI with Laravel for API documentation?
- Use `swagger-ui-dist` for static hosting: place the downloaded assets in Laravel’s `public/swagger-ui` folder, then create a route (e.g., `/docs`) pointing to a Blade view embedding the Swagger UI bundle. For dynamic loading, install `swagger-ui` via npm and bundle it with Laravel Mix/Vite. Reference your Laravel-generated OpenAPI spec (e.g., `/docs/api.json`) in the Swagger UI config.
- Which Laravel packages generate OpenAPI specs compatible with Swagger UI?
- Use `darkaonline/l5-swagger` or `zircote/swagger-php` to generate OpenAPI specs (JSON/YAML) from Laravel controllers. These specs can be directly consumed by Swagger UI via the `url` config option. Ensure your spec version (OpenAPI 2.0/3.x) matches Swagger UI’s supported versions (v5.x supports 2.0/3.0–3.2).
- Can Swagger UI handle OAuth2 authentication for my Laravel API?
- Yes, but securely: configure Swagger UI’s `oauth2RedirectUrl` and `oauth2ClientId` in the config, but avoid exposing `clientSecret` in production. Use Laravel’s OAuth2 middleware (e.g., `lcobucci/jwt`) and proxy auth tokens via a dedicated `/auth` endpoint. For testing, use mock credentials or a staging OAuth2 server.
- What’s the best way to host Swagger UI in production for Laravel APIs?
- For simplicity, serve `swagger-ui-dist` from Laravel’s `public` folder via a dedicated route (e.g., `/docs`). For scalability, host it independently (e.g., subdomain `docs.yourapp.com`) or containerize it with Docker. Ensure your OpenAPI spec is accessible via a public URL or secure endpoint (e.g., `/api/docs`).
- How do I customize Swagger UI’s appearance or add plugins for Laravel?
- Extend Swagger UI’s default theme by overriding CSS in your Laravel assets or using the `dom_id` and `layout` config options. Add plugins (e.g., `SwaggerUIBundle.plugins.DownloadUrl`) via the `plugins` array in the config. For deep linking, use `urls` config to map endpoints to specific docs sections. Test customizations locally before deployment.
- Will Swagger UI work with Laravel’s API keys or custom auth headers?
- Swagger UI supports API keys via the `apiKey` config, but headers like `Authorization` or `X-Custom-Token` require manual handling. Use the `requestInterceptor` config to inject headers dynamically. For testing, mock headers in the browser’s DevTools or use a proxy server to forward requests. Note: Swagger UI cannot test `Cookie`-based auth due to browser limitations.
- Is Swagger UI compatible with Laravel 10 and modern PHP versions?
- Yes, Swagger UI (v5.x) works with Laravel 10+ and PHP 8.0+. Ensure your OpenAPI spec generator (e.g., `l5-swagger`) is updated to support OpenAPI 3.x. Test with Laravel’s built-in server (`php artisan serve`) or a production server (e.g., Nginx) to verify compatibility. Check the `swagger-ui-dist` releases for the latest asset bundles.
- How do I test Swagger UI locally during Laravel development?
- Generate your OpenAPI spec (e.g., `php artisan l5-swagger:generate`), then reference it in Swagger UI’s config. Use Laravel’s `php artisan serve` and navigate to `/docs`. For OAuth2 testing, configure a mock auth server (e.g., `mockoon`) or use Laravel Sanctum’s temporary tokens. Validate requests with Postman or cURL before testing in Swagger UI.
- Can I use Swagger UI with Laravel’s Inertia.js or Livewire for SPA-like docs?
- Yes, dynamically load `swagger-ui` via npm and bundle it with Laravel Mix/Vite. Mount Swagger UI in an Inertia page or Livewire component using the `SwaggerUIBundle` class. Pass the OpenAPI spec URL via props or Laravel’s shared data. For Livewire, use `wire:ignore` to prevent reactivity conflicts with Swagger UI’s JavaScript.
- What are the alternatives to Swagger UI for Laravel API documentation?
- Alternatives include **Redoc** (simpler, Markdown-based), **Stoplight Elements** (modern UI), or **Postman’s API Network** (for Postman users). For Laravel-specific tools, consider `darkaonline/l5-swagger`’s built-in UI or **API Blueprint** with tools like **AgileAPI**. Swagger UI is preferred for interactive testing, while Redoc excels for static, embeddable docs.
Weaver
How can I help you explore Laravel packages today?