Weave Code
Swagger Ui Laravel Package
swagger-api/swagger-ui
Swagger UI renders your OpenAPI spec as interactive API documentation, letting developers visualize and test endpoints directly in the browser. Drop-in npm packages, CDN bundles, and Docker images make setup easy.
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 install Swagger UI in a Laravel application?
- Install swagger-api/swagger-ui via Composer or the swagger-ui-dist npm package, then copy the dist assets into Laravel's public/swagger-ui directory. Create a Blade view or static HTML page that loads swagger-ui.css and swagger-ui-bundle.js and initializes SwaggerUIBundle with the URL of your OpenAPI JSON or YAML file. Many teams instead use darkaonline/l5-swagger, which installs Swagger UI assets and publishes a ready-made docs route for Laravel.
- Does swagger-api/swagger-ui work with Laravel 10 and Laravel 11?
- Yes. Swagger UI is a JavaScript, HTML, and CSS tool rather than a PHP package, so it is not tightly coupled to a Laravel version. It works with Laravel 10, Laravel 11, and older versions as long as you can serve its static assets and expose a valid OpenAPI or Swagger specification. Compatibility mainly depends on your OpenAPI spec version and browser support, not the Laravel framework version.
- How do I generate the OpenAPI spec that Swagger UI displays for a Laravel API?
- The recommended approach is darkaonline/l5-swagger, which generates OpenAPI 3.x documentation from annotations or attributes in your Laravel controllers. Alternatively, you can hand-write an OpenAPI JSON or YAML file and place it in a public path such as public/api-docs/openapi.json. Swagger UI only renders documentation when it receives a valid Swagger 2.0 or OpenAPI 3.x specification, so validate the file with Swagger Editor before deploying.
- Can Swagger UI authenticate with Laravel Sanctum or Passport?
- Yes. Swagger UI supports Bearer token authentication and OAuth2 flows, which can be defined in the securitySchemes section of your OpenAPI spec. For Sanctum, configure an HTTP bearer security scheme so developers can paste a token and use the Authorize button. For Passport OAuth2, configure the OAuth2 flow and set oauth2RedirectUrl so Swagger UI can complete the authorization code flow.
- What is the difference between swagger-ui and swagger-ui-dist for Laravel?
- The swagger-ui npm module is a traditional package intended for bundling with tools like Laravel Vite or Laravel Mix inside a single-page application. The swagger-ui-dist module is dependency-free and contains prebuilt CSS and JavaScript files that you can copy directly into Laravel's public directory. Use swagger-ui-dist for a simple Blade or static HTML docs page, and use swagger-ui when you need to import plugins or integrate documentation into a bundled frontend.
- Why is my Swagger UI page blank or failing to load my Laravel API specification?
- Common causes include an invalid OpenAPI document, an incorrect URL to the spec, missing static assets, or CORS blocking requests to your Laravel API. Check the browser network tab for 404 or CORS errors, confirm the spec URL returns valid JSON or YAML, and validate the specification in Swagger Editor. If Swagger UI is served from a different origin than the API, configure Laravel CORS middleware or serve the docs from the same domain.
- Is Swagger UI suitable for production Laravel API documentation?
- Yes, many teams serve Swagger UI in production as static assets behind authentication or on an internal documentation subdomain. Protect the docs route with Laravel middleware if the API is private, and consider disabling the Try it out feature if you do not want live requests from the browser. For very large APIs, adjust configuration such as deepLinking or lazy loading to keep rendering responsive.
- What are alternatives to Swagger UI for documenting a Laravel API?
- Redoc is a lighter option for static OpenAPI documentation but offers less interactive request testing than Swagger UI. Laravel-specific tools such as Scramble and Scribe can generate documentation or OpenAPI specs directly from your application code. Postman collections and API networks are also options, but Swagger UI remains a common choice when you want interactive OpenAPI docs hosted with your Laravel application.
- How do I customize Swagger UI theming or plugins in a Laravel project?
- Customize Swagger UI through the configuration object passed to SwaggerUIBundle, including options like docExpansion, deepLinking, presets, and plugins. You can override visual styles by loading your own CSS after swagger-ui.css in the Blade view. For advanced plugin development, install the swagger-ui npm package through Vite or Mix and import the plugin APIs instead of using the prebuilt dist files.
- Do I need to test Swagger UI documentation in Laravel CI/CD pipelines?
- Swagger UI itself is static JavaScript and does not usually need unit tests, but you should validate the OpenAPI spec that it renders. Add a CI step that generates the spec with l5-swagger or validates it with a tool such as Spectral, and include a smoke test that the documentation route returns HTTP 200. Pin your swagger-ui or swagger-ui-dist version and deploy updated assets alongside API changes to avoid documentation drift.
Weaver
How can I help you explore Laravel packages today?