- What does mezatsong/laravel-swagger-docs actually do?
- It generates a Swagger/OpenAPI specification for your API by introspecting Laravel routes, controllers, FormRequest validation rules, and Eloquent models instead of relying on hand-written annotations. Because the spec is derived from code you already maintain, it stays closer to the real implementation and reduces documentation drift. The package is a spec producer only, so serving an interactive UI is a separate concern.
- How do I install laravel-swagger-docs in a Laravel application?
- Install it as a standard Composer dependency and let Laravel package auto-discovery register the service provider. Generation is then triggered through an Artisan command that writes out the OpenAPI/Swagger document. A sensible first step is installing it on a branch and running generation against one bounded module of five to ten endpoints before rolling it out wider.
- Which Laravel and PHP versions are supported by laravel-swagger-docs?
- Confirm the supported matrix against the require constraints in the package's composer.json, since the overview does not pin exact versions. Also check the transitive constraint on the underlying swagger-php toolchain, because that dependency can cap your PHP or Laravel range independently. Compare both against your fleet's current runtime before committing to adoption.
- Is the generated Swagger spec deterministic and safe to diff in CI?
- Determinism is a hard prerequisite if you intend to commit the spec or fail a CI job when it changes, so verify it rather than assume it. Run generation twice on two different machines and diff the output, watching for unstable endpoint ordering, absolute file paths, and timestamps. If the output is not stable, pin exact versions and normalise the file with a post-processing step before diffing.
- How do I override or fix a generated schema for a single endpoint?
- Introspection heuristics will occasionally emit a type you know is wrong, so confirm whether the package exposes a supported per-endpoint override or extension point before depending on it. If no stable override API exists, keep a thin patch layer that post-processes the generated spec, or isolate the generator behind an interface so it can be swapped out. Avoid forking until you have established that the gap is permanent.
- How are enums, Eloquent casts, nullable fields, unions, and paginated responses represented?
- These are exactly the edge cases where code-derived generators tend to have gaps, and release 2.2.2 fixed three schema correctness issues including integer columns emitted as strings, boolean type generation, and nested array item schemas. Expect further gaps around enums, casts, nullable and union types, polymorphic relations, and paginated collection responses. Test those constructs explicitly and inspect the generated output by hand before trusting it.
- How do I serve Swagger UI alongside laravel-swagger-docs?
- The package produces the OpenAPI document, while rendering an interactive reference is a separate layer you still need to provide. You can serve the spec with an existing L5-Swagger installation used purely as a viewer, or host a static Swagger UI build that loads the generated JSON or YAML. Keeping the producer and the viewer decoupled makes the generator replaceable if the project stalls.
- How does laravel-swagger-docs compare with L5-Swagger and Scribe?
- L5-Swagger and Scribe occupy the same slot but take a different route, leaning on hand-written annotations or docblocks, whereas this package derives the spec from routes, FormRequests, and models. Code-derived output drifts less when validation rules change, but its accuracy depends on the introspection heuristics being correct. Choosing it is an explicit bet on code-derived specs over annotation-derived ones, which is reasonable as long as you validate the output.
- What licence and transitive dependencies does laravel-swagger-docs use?
- Check the licence on Packagist and in the repository, along with the full dependency tree pulled in by the OpenAPI toolchain it wraps. A pinned swagger-php version is the dependency most likely to constrain your PHP and Laravel upgrade path. Review both as part of your licence and security posture before production adoption.
- Is laravel-swagger-docs production ready and actively maintained?
- The dominant risk is maintainer concentration: a single primary maintainer plus first-time contributors in the 2.2.2 release means the bus factor is low. Pin exact patch versions, keep your own upgrade policy, and budget for vendoring or forking if maintenance stalls. Treat the generated spec as a controlled artifact reviewed in CI rather than a silently trusted output.