Autodoc Laravel Laravel Package

Product Decisions This Supports

• API documentation as a shipped artifact. This package lets the OpenAPI spec be generated from the Laravel route/controller/middleware layer rather than hand-maintained, which turns "we'll document the API later" into a CI-checkable deliverable. That directly supports decisions about when an API is ready to be called "public" or "partner-ready."
• Build vs. buy on developer experience tooling. The alternative is a hosted docs platform, a hand-written spec, or a dedicated technical writer. This is a cheap way to test whether API consumers actually use a spec before committing budget to a portal.
• Downstream tooling enablement. A generated spec is the input to SDK generation, contract tests, gateway import, Postman/Bruno collections, and mock servers. Choosing to generate it is a prerequisite decision for any of those roadmap items.
• v2.2.2 specifically — how authorization is represented externally. The new laravel.abilities_as_security_roles option lets you suppress can:<ability> entries from the generated security requirements. This matters for two product calls: (a) whether your published spec should describe authentication scheme only (Sanctum/Passport) versus per-endpoint permissions, and (b) whether third-party integrators should see your internal ability names at all. Ability names are effectively internal domain vocabulary; exposing them in a partner-facing spec is a small information-disclosure and API-surface-commitment decision, not just a formatting preference. The flag gives you a supported way to make that call per environment instead of post-processing the YAML.
• Migration/versioning decisions. A spec that accurately reflects middleware and authorization requirements makes it practical to diff API surface between releases and to reason about what breaking a permission change actually looks like to a consumer.

When to Consider This Package

Consider it when:

• The product surface is a Laravel HTTP API with routes, controllers, form requests, and middleware as the real source of truth — not a separate spec repo.
• You have or expect external consumers (partners, mobile clients, internal platform teams) and documentation drift is a recurring complaint.
• You want the spec in version control and in CI, generated on every build, with no runtime dependency in production and no per-seat documentation SaaS cost.
• Your authorization is expressed in a way the generator can read (policies/gates, Sanctum or Passport abilities) and you're willing to accept generated output as a starting point that gets reviewed, not published blindly.
• You need environment-specific output — e.g. internal specs that list abilities, partner-facing specs that don't. The v2.2.2 toggle is directly useful here; note it is opt-in, so existing output is unchanged unless you set it, which keeps the upgrade low-risk.

Look elsewhere when:

• You are not Laravel-first, or the estate is polyglot and needs one spec pipeline across services.
• The contract is GraphQL, gRPC, or event-driven — the route-introspection model does not map.
• You need a hosted, interactive "try it" experience with auth, team permissions, and usage analytics; that is a portal product, not a generator.
• You need formal API governance — style linting, spectral rulesets, versioning policy enforcement, monetization. A generator can feed those tools but does not replace them.
• Your authorization is entirely custom or your ability names are meaningless to consumers. The new flag reduces the noise but does not make the generated security section authoritative; treat its output as advisory and document permissions separately.

How to Pitch It (Stakeholders)

For executives: We can publish an accurate API reference for our Laravel services without a documentation project or a SaaS subscription. The spec is generated from the code we already ship, so it cannot drift the way a wiki does, and it unblocks partner onboarding, SDK generation, and gateway import — all of which currently start with someone reading our source. Cost is a config file and a CI step. Risk is low: the latest patch is a single opt-in configuration flag that changes nothing unless we enable it, and it lets us keep internal permission names out of partner-facing documentation.

For engineering: Documentation is derived from routes, controllers, middleware, and authorization definitions, so it stays honest as long as the code does. No production runtime dependency; generation runs in CI and the output is diffable, which means API surface changes show up in code review. The v2.2.2 option, laravel.abilities_as_security_roles, controls whether can:<ability> entries appear as security roles in the spec — set it off when abilities are internal vocabulary or when consumers should reason about authentication only. Default behavior is unchanged, so adoption is a config edit plus a review of the first generated diff, and we should budget that review explicitly: the generated spec is a draft to be corrected, not ground truth.