Laravel Swagger Laravel Package

Getting Started

Install the package and generate your first spec in three commands:

composer require ronasit/laravel-swagger --dev
php artisan vendor:publish --tag=swagger
php artisan swagger:generate

The published config/swagger.php is your entry point — it controls the output path, the route group/base path the generator inspects, and which middleware/auth is applied. The generated spec lands in storage/api-docs/ by default; you can serve it via the swagger:serve command or point Swagger UI at the file.

First use case: pick one controller with a couple of actions, add the response/request attributes (or let the generator infer from FormRequest rules), and run swagger:generate against it. The most useful thing to check first is how your DTOs/Resources appear in components.schemas — the generator walks controller return types, so well-typed actions produce good schemas with zero config.

If you're on 3.3, invokable controllers (__invoke) are now supported, including route-model binding and DI resolved through contracts — previously these produced empty or malformed paths.

Implementation Patterns

Type-driven generation. The core workflow is: typehint your controller return types and FormRequests, then let the generator derive the spec. Annotate only the gaps (auth, odd status codes, headers). Treat the generated JSON as a build artifact, not a source file — commit it only if you're using it for contract diffing in CI.

FormRequests as the request-body source. Rules become schema properties; custom Rule objects won't translate, so back them with a withValidator-free rules() where possible or annotate manually.

Query params from Eloquent helpers (new in 3.3). with[] and with_count[] are now expanded into separate documented query parameters per relation instead of a single opaque array param. If you have endpoints using ?with=posts,comments, the spec now surfaces with[posts], with[comments], etc., which is much friendlier in Swagger UI. Check any generated clients or contract tests that pinned the old shape.

Invocable controllers. For single-action controllers use __invoke as normal; 3.3 resolves constructor dependencies bound to contracts via the container. If your invokable takes an interface in the constructor, it will now document correctly rather than silently skipping.

Versioned docs. Use the versioning option to emit multiple specs (e.g. v1, v2) from different route prefixes. 3.3 fixes a bug where versioned documentation produced incorrect output — regenerate after upgrading if you relied on this.

CI integration. Generate into a temp path during tests and diff against a committed golden file. This catches accidental API surface changes in PRs. The parallel-testing token work in 3.3 means generation under ParaTest/pest --parallel no longer collides on the temp file.

Gotchas and Tips

• Empty temp file overwriting production docs was a real bug (fixed in 3.3). Previously, if the temp temp_documentation.json was empty at the save step, production data could be clobbered. If you're pinned below 3.3 and run generation in CI with --quiet, you may have silently published empty specs. Upgrade and re-verify your committed spec.
• Local driver fix (3.3). If you generate to a local filesystem disk, earlier versions had path resolution issues. Confirm the documentation.disk / path config after upgrading if you were mapping a custom disk.
• OpenAPI 3.0 strictness. PR #203 aligned SwaggerService and SwaggerSpecValidator with OpenAPI 3.0. If you were emitting 3.1-flavoured constructs (e.g. type: ["string","null"] unions, examples on schema level differing from 3.1 rules), validation may now flag them. Run swagger:validate in your pipeline and fix schemas rather than relaxing validation.
• Error page rendering. 3.3 reworked the 500 error page (font size, trace formatting, removed the type key from traces) — a nicer debugging experience, but if you snapshot the error HTML in tests, update fixtures.
• Parallel testing. If you run swagger:generate inside parallel test suites, ensure the newly mocked token is in place; otherwise concurrent runs can race on the same temp file. Clear stale temp_documentation.json in setUp/tearDown.
• Invokable DI gotchas. Contract-bound dependencies resolve, but if you bind to a closure returning a non-class or rely on contextual binding, the generator may still struggle to reflect — fall back to explicit annotations on those actions.
• PHPUnit/PHP 8.4 compatibility. 3.3 adds PHP 8.4 to the test matrix and adjusts PHPUnit 12 support (one attempt reverted). If you're on PHPUnit 12 in your own suite and use the package's testing helpers, verify they still run — pin exact versions if you hit flakiness.
• Laravel Pint adoption. The package now ships a Pint config, which is irrelevant to consumers, but if you copy snippets from package source into your app, expect a different style baseline.
• Debugging bad schemas. When a schema comes out empty, the usual causes are: return type is mixed/array without a generic docblock, the action returns a JsonResponse built dynamically, or an abort()/exception path is being inferred as the success response. Add explicit return type hints and @response annotations at that boundary.
• Extension point: the generator's driver/middleware pipeline is where you hook custom logic — a custom middleware that inspects route metadata is the cleanest place to inject cross-cutting docs (tenant headers, feature flags) rather than editing generated files.