Laravel Api Laravel Package

Product Decisions This Supports

• Build vs. buy on the API documentation layer. The core value proposition is eliminating hand-maintained OpenAPI YAML and annotation blocks: docs are derived from PHPDoc, which most Laravel teams already write. That reframes the build option from "write a spec generator" to "adopt a thin generator + keep PHPDoc disciplined" — a materially cheaper path for teams that have been deferring documentation.
• API versioning strategy. The package's headline is versioned APIs with generated OpenAPI 3.0. If we are approaching the first breaking change on a public or partner-facing API, this is a candidate mechanism to evaluate against URL-prefix versioning, header/media-type negotiation, or a gateway-level strategy. Decision needed: does versioning live in the framework layer or the routing/gateway layer?
• Scope of API documentation as a roadmap commitment. If docs are a contractual or sales-enablement requirement (partner integrations, procurement reviews, external developers), generating them from source reduces the ongoing cost of that commitment and makes "keep docs current" a defensible promise rather than a perpetual backlog item.
• Time-to-first-endpoint for internal and admin surfaces. CRUD scaffolding plus middleware cascades directly affects the cost estimate for back-office tooling, internal admin APIs, and MVP endpoints. This informs whether we staff a platform team to build a house generator or take a dependency.
• Documentation drift as a quality metric. Because the spec is derived from the code rather than authored alongside it, doc drift becomes a linting/discipline problem rather than a reconciliation project. That is a decision lever when weighing API quality investments.
• Use cases this fits: internal service APIs, admin/back-office endpoints, MVP and pilot APIs where a spec is needed for a partner but the surface is still moving, and Laravel monoliths being gradually exposed as an API.

When to Consider This Package

Adopt-or-pilot when most of the following hold:

• The stack is Laravel/PHP and will remain so for the foreseeable life of the service.
• The team already annotates with PHPDoc, or is willing to make it a review-enforced convention. The package's whole premise collapses if PHPDoc is treated as optional.
• OpenAPI 3.0 is sufficient. If a consumer requires 3.1, spec-first design with JSON Schema validation, or codegen pipelines pinned to a specific dialect, validate compatibility before committing.
• The team is small and has no dedicated technical writer; the alternative is not a better docs pipeline, it is no docs pipeline.
• The API surface is expected to version — i.e., there are external or partner consumers whose integrations cannot be broken casually.
• We are willing to run a bounded pilot on one non-critical service rather than standardizing org-wide on day one.

Look elsewhere when:

• Community support and longevity matter more than fit. 13 stars and an unknown repository is a bus-factor-of-one signal. If the team needs Stack Overflow answers, third-party tutorials, or a plausible five-year maintenance story, prefer a more established generator (e.g., dedoc/scramble or L5-Swagger) or absorb the cost in-house.
• The API is contract-first by organizational policy — spec authored by design, code generated or validated against it. This package inverts that flow.
• We need GraphQL, gRPC, or async/event schema documentation.
• We need deep auth/policy/rate-limit modeling in the generated spec beyond what middleware cascades expose.
• The service is polyglot and the docs pipeline must span non-PHP services; a language-neutral spec source is the better investment.
• Procurement or security review requires a maintained vendor, CVE process, or SLAs.

How to Pitch It (Stakeholders)

For executives: This is an MIT-licensed Laravel package that turns the PHPDoc comments our engineers already write into a published OpenAPI 3.0 spec, and scaffolds versioned CRUD endpoints with a middleware cascade. The business case is cost avoidance: it removes the duplicate work of hand-authoring and hand-maintaining API documentation, which is typically the first thing to slip when delivery pressure rises. For any roadmap item that involves external or partner integrations, "we publish a current API spec" becomes cheap to promise instead of expensive to sustain. Cost of adoption is low and reversible — it is a Composer dependency, not a platform commitment.

For engineering: One dependency gives us generated OpenAPI 3.0 from PHPDoc (no annotations, no YAML to keep in sync), opinionated API versioning, CRUD scaffolding, and composable middleware cascades. It fits the Laravel idioms we already use and removes boilerplate we currently rewrite per service. Trade-off to be explicit about: the project is early-stage with a very small community, so we should pilot on one service behind a thin internal interface, keep the spec-generation step isolated in CI so the generator is swappable, and not let its conventions leak into domain code. If the pilot holds, we standardize; if not, we have lost a sprint, not an architecture.