Openapi Command Bundle Laravel Package

Product Decisions This Supports

• API contract governance: This package exposes console commands that generate and warm OpenAPI documents, which is the plumbing behind "our API spec is always current and reviewable" — a prerequisite for contract testing, SDK generation, and public developer docs.
• Build vs. buy for API tooling: Rather than hand-rolling spec generation scripts inside each service, this centralizes it as a command surface. Relevant to roadmap items like "self-serve API docs," "partner SDKs," and "breaking-change detection in CI."
• Release/CI pipeline design: The 0.15.0 change (build-time warming is now opt-in) means the default behavior of your build pipeline changes — warming no longer happens automatically. This directly affects any roadmap commitment around "spec artifacts are published on every deploy." If spec freshness is a customer-facing promise, warming must be explicitly enabled in configuration before upgrading.
• Use cases it unlocks: generated specs as a build artifact, diffing specs between releases, feeding downstream codegen, and gating merges on spec validity.
• Risk sizing for upgrade planning: Version 0.x signals an unstable API surface. The default-behavior flip in a minor release is consistent with that; budget upgrade work per release rather than assuming patch-level safety.

When to Consider This Package

Adopt when:

• You have (or are standardizing on) OpenAPI as the source of truth and want generation/warming driven from the console rather than bespoke scripts.
• You want spec generation to run as a discrete, cacheable step in CI or a deploy pipeline, not inline in request handling.
• You are comfortable pinning a 0.x dependency and reading changelogs on each bump.
• You need the opt-in behavior: you want control over when specs are warmed, and prefer explicit enablement over implicit build-time work (0.15.0 is a strict improvement here — no hidden work during builds).

Look elsewhere / deprioritize when:

• Your stack is Laravel-first and you expect first-class framework integration. The package naming (openapi-command-bundle) and its release cadence suggest a Symfony-oriented bundle; confirm the Laravel fit before committing, since this assessment is being read as a Laravel/PHP evaluation.
• Your spec generation needs are trivial enough that a single Artisan command or a static file covers it.
• You depend on build-time warming happening implicitly. 0.15.0 makes warming opt-in — upgrading will silently stop producing warmed documents unless you enable it. Treat this as a breaking behavioral change for pipelines: pin 0.14.2 until you've added the opt-in flag and verified your artifacts.
• You require a stable public API contract (pre-1.0 releases may keep shifting defaults).

How to Pitch It (Stakeholders)

For executives: This is a small, single-purpose PHP dependency that makes our API specifications a generated, reproducible artifact instead of something maintained by hand. The value is in trust and speed: partner-facing docs, SDK generation, and change detection all get a reliable input. Cost is low and contained — it's tooling, not runtime infrastructure, so it cannot degrade production traffic. The tradeoff is dependency hygiene: it's pre-1.0, so we pin versions and review each release. The 0.15.0 release removes implicit work from the build, which is directionally good for build times and predictability, but it requires a one-line configuration change so our spec artifacts keep being produced.

For engineering: 0.15.0 makes build-time warming of OpenAPI documents opt-in (PR #58). Concretely: if any pipeline relies on documents being warmed as a side effect of the build, that stops happening after upgrade. Action items: (1) pin 0.14.2 on release branches until we've added the explicit opt-in configuration, (2) add a CI assertion that the warmed spec artifact exists and is non-empty, so this class of silent regression fails loudly next time, (3) note the package's Symfony-flavored surface — if we're consuming it from Laravel, confirm our integration path before it becomes load-bearing. Net: the change is small and correct, but it is a default-behavior change in a minor version and should be treated as breaking.

Recommendation: Upgrade deliberately, not automatically. Add the opt-in flag and an artifact-presence check in the same change.