Autodoc Laravel Laravel Package

Technical Evaluation

Scope of the change. v2.2.2 adds a single configuration flag, laravel.abilities_as_security_roles, that suppresses can:<ability> entries from the generated security requirements. This is an additive, documentation-generation-only change — it alters what the auto-doc output claims about authentication/authorization, not what the application actually enforces at runtime. Confirm that before assuming zero runtime blast radius.

Architecture fit. The package lives in the developer-tooling tier (dev dependency, CI/codegen step), introspecting route and middleware definitions to emit OpenAPI-style specs. can:<ability> strings are Laravel Gate/Policy checks — in practice usually produced by spatie/laravel-permission or explicit can: middleware — and are not OAuth2/OpenID scopes. Emitting them inside the security block has long been a fidelity problem for generated specs: consumer SDK generators and API gateways interpret them as scopes and either reject the spec or fabricate bogus scope parameters. This flag is a targeted correctness fix that aligns the generated contract with real auth schemes (Sanctum, Passport, bearer). That is a good architectural direction for the package.

Integration feasibility. High. Config-only, no code changes, no new dependencies, no migration. Realistically a one-line edit to the published config/autodoc.php (or equivalent) followed by a docs regeneration and a diff review.

Technical risk. Low overall, with three concrete caveats:

1. Default value is the whole story. If the default preserves current behavior (flag defaults such that can: roles are still emitted), the upgrade is inert and safe but requires deliberate opt-in — easy to adopt and forget. If the default flips behavior, every consuming team's committed spec changes on composer update, breaking schema-diff CI checks and downstream SDK generation without a code change on their side. This single fact determines whether v2.2.2 is a trivial patch or effectively a breaking change for spec consumers.
2. Loss of expressiveness. Dropping can: entries removes the only machine-readable signal of fine-grained authorization from the spec. If downstream teams relied on those entries for permission modeling (even imperfectly), they lose it silently. Mitigation is documenting abilities in route descriptions or a vendor extension, which is manual work the package does not currently automate.
3. Evidence basis is thin. The entire input here is a one-line changelog. No release cadence history, no prior assessment, no dependency or Laravel-version support matrix, no maintainer/bus-factor signal. The risk rating above is about this change; it says nothing about the package's overall health, which remains unassessed.

Key questions for the maintainer / owning team:

• What is the default value, and is the change called out as behavior-affecting in the upgrade guide?
• Does the flag affect only emitted spec output, or does any runtime middleware/validation path also consume it?
• Is there per-route or per-middleware-group override granularity, or is it a global switch?
• Does it interact with securitySchemes generation — e.g. does a route with only can: middleware end up with an empty security array, and is that valid/desired output?
• Does it cover can: appearing under middleware aliases, groups, or nested controllers?
• Supported Laravel and spatie/laravel-permission version range for v2.2.x?

Integration Approach

Stack fit. Assumes a Laravel application already generating API documentation in CI or as a pre-release step. The flag is only meaningful where route authorization is expressed through Gate abilities — i.e. teams using policies or spatie/laravel-permission. Teams whose auth is purely token/session-based, or who never emitted can: entries, get no value and should skip the upgrade rather than absorb the diff noise.

Migration path. Treat it as a config change, not a version bump:

1. Pin to ^2.2.2 in require-dev — this package should not be a production dependency.
2. Publish (or diff) the config and set laravel.abilities_as_security_roles explicitly rather than relying on the default — explicit is auditable and survives future default changes.
3. Regenerate the spec into a temp file and diff against the committed artifact.
4. Review the diff for empty security blocks and for routes that previously advertised abilities and now advertise nothing. Each such route needs a prose description naming the required permission, or the spec becomes misleading rather than merely noisy.
5. Commit the regenerated spec; let contract tests and SDK generation run against it.

Compatibility. Backwards compatible at the PHP level; potentially not backwards compatible at the generated-artifact level, which is the interface that actually matters to consumers. Coordinate with anyone consuming the published spec (mobile, partner integrations, gateway config) before merging, even if the diff looks small.

Sequencing. Do this as an isolated PR in a low-traffic window, ahead of — not bundled with — any other spec-affecting change, so an unexpected diff is unambiguously attributable. Run it once in a non-blocking CI job first to observe the diff without gating builds; promote to blocking only after the output stabilizes.

Operational Impact

Maintenance. Negligible ongoing cost: one config key, no new moving parts. The real maintenance burden is the manual descriptions you must add for routes that lose their can: entries — a one-time, per-route cost proportional to how much fine-grained authorization you expose.

Support. Low. The main support surface is "why did my spec change after a patch upgrade?" — pre-empt it by landing the config change and the regenerated spec in the same commit, with the flag explicitly set. Document the decision in the repo so the next maintainer does not revert it as noise.

Scaling. Unaffected — this is build-time codegen. The flag scales fine across many routes since it is a global switch. The thing that does not scale is per-route documentation of abilities if you have hundreds of ability-gated endpoints; if that count is high, budget for a generator enhancement rather than hand-writing descriptions.

Failure modes.

• Silent under-documentation: abilities dropped from the spec, consumers assume any authenticated token suffices, integration tests pass locally but production returns 403. Highest-severity failure mode here.
• Empty security blocks: a route whose only auth signal was can: now advertises no security at all — arguably worse than the original noise, and something OpenAPI linters may flag or ignore.
• CI drift: committed spec falls out of sync with a regenerated one, producing recurring diff failures unrelated to feature work.
• Default ambiguity: if the default flips in a later patch, teams that never set the flag explicitly get a second, unnoticed behavior change.

Ramp-up. Minutes for a Laravel-fluent engineer: read the config, flip the flag, regenerate, review the diff. The non-obvious part is judgment, not mechanics — deciding which dropped abilities must be preserved as documentation. That review needs someone who knows the authorization model, not just the build. Budget a half-day for the first spec diff review on a mid-sized API, and near-zero thereafter.