Autodoc Laravel Laravel Package

Getting Started

• Install with composer require 421c/autodoc-laravel (dev-only is usually fine: --dev), then publish the config with the package's publish tag (check php artisan vendor:publish output; typically --tag=autodoc-config).
• Look first at config/autodoc.php. The laravel block controls how Laravel route metadata is translated into the OpenAPI document, including how can:<ability> middleware becomes OpenAPI security roles. The new v2.2.2 key lives here: laravel.abilities_as_security_roles (default true).
• Generate the spec with the package's Artisan command (php artisan list | grep autodoc to confirm the exact name, commonly autodoc:generate). Inspect the output file (JSON/YAML) rather than trusting the config alone.
• First use case: take one small authenticated API group, e.g. routes under /api guarded by auth:sanctum plus can:view-invoice. Generate the docs and verify:
  • a securitySchemes entry exists for your auth guard, and
  • each can:<ability> middleware appears as a security requirement only if you want abilities treated as roles.
• If your API uses OAuth scopes or fixed roles rather than Laravel abilities, set laravel.abilities_as_security_roles => false early and define security schemes explicitly. This is the main decision to make on day one, because it changes the shape of every secured operation in the generated document.

Implementation Patterns

• Route-driven generation per surface. Scope generation by route prefix, name pattern, or middleware in the laravel config rather than documenting the whole app. Generate separate specs for api, admin, and internal endpoints if they have different auth models.
• Treat the spec as a build artifact. Run the generate command in CI, fail or warn on git diff of the output, and publish the artifact to your docs host. This keeps documentation drift visible in pull requests.
• Abilities-as-roles (default). With abilities_as_security_roles left true, can:approve-refund becomes a role-like requirement named after the ability. This works well when your abilities are stable, human-readable, and align with how consumers reason about permissions.
• Abilities omitted (v2.2.2 option). Set laravel.abilities_as_security_roles => false when your security model is scope- or role-based at the gateway, or when ability names are internal implementation details (can:update,App\Models\Invoice). Then declare security requirements via config/annotations and keep the generated auth scheme but not the ability roles.
• Environment-aware config. Drive the flag from an env var so local docs can be verbose while public docs omit internal abilities:

  'abilities_as_security_roles' => env('AUTODOC_ABILITIES_AS_SECURITY_ROLES', true),
  

• Layer annotations for exceptions. Use the generator for the bulk of routes, and per-route OpenAPI annotations/attributes for edge cases (file uploads, polymorphic responses, custom security). Keep these next to the controller so they are reviewed with code changes.
• Pair with a viewer in development. Point Swagger UI / Redoc / Scalar at the generated file in a local route or static host; regenerating and refreshing is the fastest feedback loop when tuning route filters and security output.

Gotchas and Tips

• Published configs go stale. If you published config/autodoc.php before v2.2.2, the new laravel.abilities_as_security_roles key will be absent. Diff the package's config against yours after upgrades; behavior falls back to the package default (true), so nothing breaks, but the option silently does nothing until merged.
• Clear caches before generating. php artisan config:clear and php artisan route:clear after config or route changes. Stale cached routes are the most common cause of "my new endpoint isn't in the docs."
• Only can: middleware is detected. Authorization performed inside controllers ($this->authorize(...), Gate::authorize, policy calls, form requests) will not produce security roles. If your abilities are enforced in code rather than middleware, the generated security section will understate requirements — document those explicitly or move the check into middleware.
• Ability names with parameters are noisy. can:update,invoice style middleware can yield role strings containing model class names or arguments. Prefer named abilities (e.g. update-invoice) if you keep abilities_as_security_roles enabled, otherwise disable it.
• OpenAPI security semantics bite. Multiple roles inside one security requirement object are AND-ed; multiple objects are OR-ed. Verify the generated nesting matches intent before publishing.
• Don't leak internals. Ability names and policy names can reveal domain structure. For public-facing docs, set abilities_as_security_roles => false and expose only the auth scheme plus consumer-facing scopes.
• Boolean env casting. Laravel's env() handles "false"/"true" strings, but values like "0" or empty strings can surprise you. Prefer explicit booleans and confirm with php artisan config:show autodoc (or tinker) after setting the env var.
• Extension point: post-process the generated document if needed (custom security scheme injection, path filtering, tag normalization) rather than forking templates. Keep that post-processing in a small service and run it in the same CI step as generation so local and CI output match.