Weave Code
Laravel Swagger Laravel Package
ronasit/laravel-swagger
Generate Swagger/OpenAPI documentation for your Laravel API directly from annotations in your controllers, with automatic route discovery, a bundled UI, and support for the OpenAPI spec.
Laravel-Swagger is a fully automate tool which allows to generate and save swagger-based documentation after successful completing your application's feature tests.
Frequently asked questions about Laravel Swagger
- What is ronasit/laravel-swagger used for?
- It generates Swagger/OpenAPI documentation for a Laravel API by introspecting your application's routes and controllers, including annotations, and then serves an interactive docs UI. It is a build-time documentation tool rather than a request-path dependency, so it does not sit in the hot path of the API it documents. The generated spec can be saved to a storage driver and validated.
- How do I install and configure laravel-swagger?
- Install it with Composer, publish its configuration, and run the package's generation command to produce the spec. UI serving is opt-in, so you can generate documentation without exposing the bundled UI. Check the README for the exact command names and storage driver settings for your version.
- Which Laravel and PHP versions does laravel-swagger 3.3 support?
- Version 3.3 tests PHP 8.4, and the package is built for Laravel applications that use its container and route conventions. The release notes do not settle every question about Laravel 12 coverage, so confirm the Composer constraints and CI matrix before upgrading. Run your own test suite against your pinned Laravel and Symfony versions.
- Does laravel-swagger support invokable controllers and dependency injection?
- Yes. Version 3.3 includes a fix for invokable controllers that receive dependencies via contracts, so single-action controller patterns are handled correctly. This closes a correctness gap that affected modern Laravel controller styles. You should still test generation for any custom container bindings your API relies on.
- Does it document Eloquent with and with_count query parameters?
- Yes. Recent releases expand with[] and with_count[] relation-inclusion parameters into discrete query parameters in the generated spec. That makes the documentation more accurate for APIs that expose Eloquent relationship loading. Regenerate and inspect the spec if you rely on these parameters.
- Is laravel-swagger compatible with OpenAPI 3.0 or 3.1?
- The 3.3 validator work aligns with the OpenAPI 3.0 specification, and the stricter validation can surface spec defects that previously passed. Confirm whether your target is OpenAPI 3.0.x or 3.1.x before committing, because the two differ. If your CI gates on spec validation, expect possible new failures at upgrade time.
- Why did my generated Swagger spec start failing validation after upgrading?
- Version 3.3 tightened SwaggerService and SwaggerSpecValidator behavior against OpenAPI 3.0, so previously passing specs may now fail. Those failures usually reflect real defects in the generated document rather than a package regression. Treat the validator as a CI gate and fix the spec, or pin the package version while you migrate.
- Can laravel-swagger document versioned APIs like /api/v1 and /api/v2?
- Version 3.3 includes a fix for versioned API documentation, but versioned routes have been a fragile area in earlier releases. If you run multiple API versions, test generation for every version rather than spot-checking one. Inspect the saved artifacts to confirm each version's paths and schemas are correct.
- Is it safe to generate Swagger docs in production?
- Treat any generation step that writes to a shared or production location as destructive. A 3.3 fix addresses a prior failure mode where an empty temp_documentation.json could overwrite previously generated production documentation. Gate production writes behind a spec diff, and verify the package's error page and stack-trace handling are disabled or sanitized outside local and staging.
- How does laravel-swagger compare with Scribe or l5-swagger?
- laravel-swagger focuses on introspecting Laravel routes and controllers, generating an OpenAPI spec, and serving a bundled UI. Scribe is also annotation- and route-driven but emphasizes human-readable API docs, while l5-swagger typically pairs with zircote/swagger-php for annotation-based OpenAPI generation. Choose based on whether you want Laravel-native route discovery, OpenAPI validation, and a bundled UI in one package.
Weaver
How can I help you explore Laravel packages today?