Laravel Api Docs Laravel Package

Product Decisions This Supports

Build vs. buy for API documentation. Scramble (dedoc/scramble) derives an OpenAPI document from Laravel routes, form requests, API resources, and validation rules rather than from hand-written annotations. That makes "how do we document the API?" a small, reversible decision instead of a tooling program — no separate spec-authoring workflow, no parallel source of truth to keep in sync.

Code-first vs. contract-first. If the team already treats framework code as the source of truth, this package lets the OpenAPI contract be a generated artifact consumed by downstream tools (Postman/Insomnia import, API gateways, client/SDK generators, docs portals) without asking engineers to maintain a YAML file by hand. The inverse decision — contract-first with codegen — remains a different (and still valid) path; this release doesn't change that calculus.

API surface as a reviewable deliverable. Because the spec is generated in CI, diffs in the OpenAPI document become a reviewable signal for unintended breaking changes to public endpoints — useful for any product with external or partner-facing consumers, and for internal platform teams publishing service contracts.

API governance and portal taxonomy. The new hierarchical tags support (OpenAPI 3.2 Tag Object fields plus a central withTags() API) lets a PM drive information architecture — grouping endpoints by product area, capability, or audience — from one configuration point rather than per-endpoint annotations. This matters if the docs site is a customer-facing surface and navigation quality is a product concern.

OpenAPI 3.2 opt-in enables downstream tooling bets. 3.2 support (opt-in; 3.1.2 remains the default document version) unblocks decisions that depend on newer spec features — richer gateway imports, tooling that has moved to 3.2, or hierarchical tag semantics. Because it's opt-in, it does not force a roadmap commitment; it de-risks one.

Roadmap timing / upgrade sequencing. The release carries a genuine breaking change (see below) inside a pre-1.0 (0.13.x) line. That is a planning input: teams should budget a version-pinning and upgrade-review policy for this dependency rather than assuming silent patch upgrades, and should decide deliberately when to move the emitted document version.

Release-specific items relevant to product scope:

• Breaking: toArray on OpenAPI objects in the Generator namespace is no longer invoked during document serialisation; serializeAs31 is called instead. toArray is retained for backward compatibility. Affected: only teams that extended or overrode toArray to customise output — they must migrate customisation into serializeAs31 (and consider how/if it should behave under 3.2). Unaffected: teams using the package as shipped.
• Behavioural: keys listed in an array validation rule are no longer required — generated schemas move closer to actual validator semantics, which reduces over-strict generated contracts.
• Behavioural: form-evaluation diagnostics are now silenced when node evaluation succeeds — less log noise, no functional change.
• Performance: additional self-output optimisation — marginal but relevant for large APIs generated in CI.

When to Consider This Package

Adopt when:

• The API is Laravel and documentation is currently stale, absent, or maintained by hand and drifting.
• The team already encodes intent in typed form requests, API resources, and validation rules — the inference has good raw material to work from.
• You want the OpenAPI document as a build artifact (CI diffing, gateway import, client generation) rather than a hand-curated file.
• You need docs with low marginal cost per endpoint, where adding an endpoint shouldn't require a second documentation task.
• You want a central place to define tag/category structure for a docs portal (relevant now with withTags() and hierarchical tags).
• You can accept pre-1.0 versioning with occasional breaking changes and are willing to pin the version and review changelogs.

Look elsewhere when:

• The codebase is not Laravel, or the API surface is largely defined outside Laravel conventions (proxied third-party APIs, hand-authored specs, non-standard routing), where inference will under-deliver.
• You require contract-first authoring, spec review before implementation, or design-time governance — annotations-first tooling (zircote/swagger-php, L5-Swagger) or a spec repository fits better.
• You need a stable, semver-guaranteed public API for the generator's internals — anything extending Generator-namespace serialisation objects is directly in the blast radius of this release, and will be again.
• You need spec features the package doesn't infer and aren't willing to add manual extensions/overrides.
• Your downstream consumers are pinned to OpenAPI 3.0.x, where generated 3.1/3.2 output requires a conversion step you'd have to own.
• Documentation must support rich hand-authored narrative, tutorials, or multi-product information architecture beyond what tag grouping provides.

Migration gate for this release: before upgrading, grep for overrides of toArray on OpenAPI objects in the Generator namespace. If none exist, the upgrade is low-risk. If they do, the customisation must move to serializeAs31, and you should verify output under both document versions if you intend to opt into 3.2.

How to Pitch It (Stakeholders)

To executives: We can produce and maintain our API documentation as a byproduct of code we already write, instead of a manual effort that decays between releases. That lowers the cost of every new endpoint and keeps partner- and customer-facing docs trustworthy. The tradeoff is that the library is still pre-1.0, so it ships occasional breaking changes; we mitigate that by pinning versions and reviewing upgrades — a small, routine engineering cost, not a program risk. This release also adds support for the newest OpenAPI version, which keeps our options open with gateways and doc tooling without committing to them today.

To engineering: v0.13.48 is a normal upgrade unless you extended toArray on OpenAPI objects in the Generator namespace — that hook is no longer called during serialisation, and customisations belong in serializeAs31 (toArray remains for compatibility but is now dead weight in the output path). OpenAPI 3.2 is opt-in and 3.1 remains the default document version, so no consumer-facing change happens unless we ask for it. Two inference improvements land as well — array-rule keys are no longer marked required, and redundant form-evaluation diagnostics are silenced — plus another small performance gain in self-output generation, which helps if we generate the spec in CI on every build. Recommended actions: pin the dependency, audit for toArray overrides, and add the generated spec to CI diffing so contract changes are visible in review.

To product/design (docs surface): The new central withTags() and hierarchical tag support mean the navigation structure of our API reference can be defined once as product information architecture, rather than emerging accidentally from endpoint order. If docs navigation is a customer experience we care about, this is the release where that becomes cheap.