Autodoc Php Laravel Package

Product Decisions This Supports

• Ship the public/partner API with docs as a first-class deliverable. An accurate OpenAPI 3.1.0 spec is the artifact that unblocks partner onboarding, developer portal pages, sandbox setup, and support runbooks. If the roadmap has an "external API" milestone, spec generation is on the critical path and this package is a candidate way to produce it without hand-maintaining YAML.
• Build vs. buy for documentation tooling. Buying a hosted docs platform still leaves you responsible for producing a correct spec. This package addresses the generation step only — it does not replace a portal, so budget decisions for hosted docs/API gateways stay separate and can be deferred.
• Downstream leverage, not just docs. A valid spec is the input to client SDK generation, Postman/Insomnia collections, contract tests in CI, gateway import (Kong/AWS API Gateway/Apigee), and increasingly to agent/LLM tooling that consumes OpenAPI. One good artifact serves several roadmap items; that changes the ROI calculation versus "we'll write docs later."
• Scope and quality decisions for existing APIs. Generating a spec from an existing PHP codebase surfaces undeclared response shapes, inconsistent error formats, and missing status codes. That is a forcing function for standardizing error envelopes and pagination — a product-quality decision, not just a docs one.
• Drift as a release gate. Once a spec exists, "spec changed without a changelog entry" or "spec differs from last published version" becomes an automatable checklist item before an API version ships, supporting deprecation and versioning policy decisions.
• Standardization across PHP services. If the org runs several Laravel/PHP services, deciding on one generation approach now avoids three teams solving it three ways. This is a cheap experiment to run in one service before writing a standard.

When to Consider This Package

Consider it when:

• The API is already implemented in PHP/Laravel and the team wants a spec derived from the code rather than maintained by hand in parallel.
• The team prefers low-ceremony, annotation-free generation (static analysis of routes/controllers) over decorating every action with attributes.
• You need OpenAPI 3.1.0 specifically — many older PHP generators still top out at 3.0.x, and 3.1's JSON Schema alignment matters if you use null types, examples, or const.
• You are spiking, not committing — a time-boxed evaluation in a non-critical service, or an internal-tooling spec, where the downside of the dependency being immature is contained.
• Licensing simplicity matters. MIT removes the procurement conversation that a commercial docs vendor triggers.

Look elsewhere when:

• Maturity is a hard requirement. 12 stars and an unknown repository is a single-maintainer risk profile. Expect no support SLA, no security response process, and a real chance of abandonment. Verify the release metadata before relying on it — the listed release date is in the future, which suggests the registry data should be independently confirmed against the actual repository and tags.
• A supported Laravel-native option already fits. For Laravel specifically, dedoc/scramble and knuckleswtf/scribe have materially larger user bases, active maintenance, and community answers. Choosing a 12-star package over them requires a concrete reason (e.g., 3.1.0 output, static analysis behavior) — not just preference.
• You need coverage breadth. Non-PHP services, polyglot monorepos, gRPC, or hand-authored spec sections (webhooks, callbacks, complex oneOf discriminators) will likely need a different toolchain; mixing generators mid-portfolio creates inconsistent specs.
• You need a docs UI. This generates the spec, not the portal. You would still pair it with Swagger UI/Redoc/Scalar or a vendor.
• Security or legal review rejects low-adoption dependencies, or the org has a minimum-adoption threshold for transitive dependencies.
• You need spec-first design. If the API contract should be authored and reviewed before implementation (public APIs with external consumers), code-derived generation inverts the workflow you want.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our API surface is growing and documentation is currently a manual, per-release cost with a long tail of partner support questions and inconsistent integration guides. This package generates an accurate OpenAPI 3.1.0 document directly from our PHP code, which means docs stay in sync with what actually ships, and the same artifact feeds partner-facing docs, client SDKs, and automated contract tests. It is MIT-licensed with no per-seat or per-call cost. The trade-off is maturity: it is a small, early-stage project, so we would adopt it behind an internal wrapper, pin the version, and treat the generated spec as a checked-in, reviewable build artifact — with a fallback to a more established generator if it disappoints. The ask is a short, time-boxed spike in one service, not a portfolio-wide commitment.

For engineering (the practical case): The pitch is no annotation tax. Hand-maintained YAML rots; attribute-based generators ask every developer to remember a second DSL. Deriving the spec from routes and controllers means the spec is wrong only when the code is wrong — a much better failure mode. Concretely, we would:

1. Run it against one existing service and diff the output against the current hand-written docs. Anything the generator gets wrong is a real documentation bug we already have.
2. Validate the emitted 3.1.0 document against a JSON Schema/OpenAPI validator in CI — the spec must be machine-valid, not just present.
3. Commit the generated file and fail the build on unexplained changes, so contract changes require a human to notice and approve them.
4. Isolate the package behind a thin internal command so replacing the generator later is a one-file change, not a refactor.

Honest risk statement to include in any write-up: low adoption (12 stars, repository not clearly identified), single-maintainer bus factor, and unverified release metadata. Mitigations are version pinning, the wrapper, and the fallback plan. The cost of trying it is measured in days; the cost of a decade of stale API docs is measured in support load and partner friction. Frame it as a reversible experiment with a defined exit criterion — if the generated spec is not 100% valid and substantially complete on the pilot service, we stop and use an established generator.