Swagger Ui Bundle Laravel Package

Getting Started

1. Install and publish. composer require the package, then publish its assets and config:

   php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"
   

   This gives you config/l5-swagger.php (paths, route, middleware, scan targets) and the Swagger UI assets under public/vendor/.
2. First place to look: config/l5-swagger.php. The keys that matter day-to-day are paths.annotations (what gets scanned), paths.docs (where api-docs.json is written, typically storage/api-docs), routes.api (default /api/documentation), and generate_always.
3. First use case — document one endpoint end to end. Add a root annotation block (Info/Server/SecurityScheme) in a dedicated class such as app/OpenApi/OpenApi.php, then annotate a single controller action, generate, and open the UI:

   php artisan l5-swagger:generate
   # browse to /api/documentation -> "Try it out" against one real endpoint
   

4. Then try the 4.5.0 feature. Drop a config.json in the project root and refresh the docs page:

   { "docExpansion": "none", "filter": true, "persistAuthorization": true, "displayRequestDuration": true }
   

   No code change, no rebuild — the UI picks it up on view. That is the fastest way to confirm the new behaviour and to start tuning the docs UX for your team.

Implementation Patterns

• Keep spec declarations out of controllers where possible. One OpenApi.php for @OA\Info, @OA\Server, @OA\SecurityScheme, and reusable @OA\Schema/@OA\Parameter components; controllers only carry per-operation annotations. This keeps diffs small when the spec evolves.
• Annotation-first vs schema-first. Annotating existing controllers is the lowest-friction path for legacy APIs; authoring a standalone YAML/JSON spec and pointing paths.docs at it suits teams that treat OpenAPI as a contract reviewed before implementation. Mixing both in one document is where most confusion starts.
• Generate at build/deploy, not at request time. Run php artisan l5-swagger:generate in your deploy pipeline (and in CI on every PR) and ship the resulting api-docs.json. Leave generate_always off in production so a page view never triggers a full annotation scan.
• Gate the docs route. Apply middleware in the config (auth/basic-auth or an IP allowlist) and disable the route entirely outside local/staging. A Swagger UI page is a complete map of your attack surface.
• config.json as the team-wide UI contract. Commit it to the repo so every developer and every environment gets identical behaviour. High-value keys for day-to-day use:
  • docExpansion: "none" for large APIs, "list" for small ones
  • filter: true — the single biggest quality-of-life win on 100+ endpoint specs
  • persistAuthorization: true — stops re-pasting tokens on every refresh
  • tryItOutEnabled: true + displayRequestDuration: true in staging for manual smoke tests
  • tagsSorter / operationsSorter for deterministic ordering in reviews
  • deepLinking: true so you can paste a link to a specific operation in a ticket or PR
• Multiple documents. For versioned or split APIs, define additional config entries and run php artisan l5-swagger:generate --all, giving each its own route and its own config.json-driven presentation if needed.
• Treat the spec as a test artifact. Add a feature test that fetches the docs JSON and asserts it decodes, has openapi/info, and contains expected paths. Documentation drift then fails CI instead of being discovered by a consumer.
• Frontend/consumer handoff. Point generated clients (openapi-generator, orval, etc.) at the generated api-docs.json; combined with deepLinking links this makes the Swagger UI the shared reference between backend and frontend.

Gotchas and Tips

• config.json is UI configuration, not spec configuration. It only affects how Swagger UI renders and behaves (expansion, filtering, auth persistence, interceptors). It does not change the generated OpenAPI document, validation, or servers — don't go looking there for schema problems.
• Placement is project root, and it must be deployed. Because it is read automatically at view time, a missing file in the release artifact silently reverts you to default UI behaviour. Verify it is committed and not excluded by .gitignore/.dockerignore.
• Malformed JSON fails silently in the browser. A trailing comma means the UI loads with defaults and only the console tells you. Validate it in CI (jq . config.json) if you rely on it.
• Caching layers. Browser cache, php artisan config:cache, and route cache can all mask changes. After editing config.json, hard-refresh; after changing route/path config, re-run config:clear and route:clear.
• Version gate. Only 4.5.0+ honours a root config.json. On older versions the equivalent was additional_config_url (or a published, overridden index.blade.php). If you have multiple projects, confirm versions before documenting the workflow in a shared runbook.
• A single malformed annotation breaks the entire generation. The command fails wholesale rather than skipping the bad block. Run generation in CI so the failure surfaces on the PR rather than at deploy time.
• @OA\Server and proxies. Behind a load balancer or in Docker, relative/derived server URLs produce wrong "Try it out" targets. Set the server explicitly per environment or use a relative URL so requests follow the current host.
• Permissions. storage/api-docs must be writable by the deploy user when generating on the server; the classic symptom is a silently stale api-docs.json.
• Don't over-invest before you need it. If plain config.json covers your needs, keep it there. Reach for a published/overridden index.blade.php or custom middleware only when you need behaviour the Swagger UI config options genuinely cannot express — that keeps you on the upgrade path.