Openapi Merge Laravel Package

Product Decisions This Supports

• Docs-as-code pipeline architecture: this package is a build-time tool for composing many OpenAPI fragments into one published spec. It supports the decision to let teams own their own spec files (per service, per domain, per partner) instead of one hand-maintained monolith — the aggregate spec becomes a generated artifact, not a source of truth.
• Build vs. buy: an off-the-shelf merger is almost always cheaper than writing one. A correct $ref-collision/paths-merge implementation is deceptively fiddly and nobody on staff wants to own it. Buy (adopt) here, and spend engineering time on spec quality and CI instead.
• Roadmap for API documentation: enables a phased roadmap — start with one spec, decompose into modules as the API surface grows, then merge for public/partner publication. No re-architecture needed to get there.
• Microservice and multi-repo coordination: when an external consumer needs a single spec for a product composed of several services, this is the glue. It turns "we can't publish a unified spec" from a blocked initiative into a CI step.
• Release 2.6.0 specifically — platform-upgrade unblocking: widening the symfony/console constraint to allow v8 means this package won't pin your console version during a Symfony 8 / newer Laravel upgrade. This is the kind of transitive-constraint change that silently blocks a framework upgrade three months later; it's cheap insurance and a reason to take the bump now rather than triage it during a time-boxed upgrade window.
• Not a differentiator: this is developer tooling and documentation infrastructure. It will never appear on a customer-facing roadmap slide, so treat it as a low-visibility enabler and keep the decision lightweight.

When to Consider This Package

Adopt when:

• You publish an OpenAPI spec today, or plan to, and more than one team/repo contributes to it.
• You have (or want) a CI step that validates and publishes a single merged spec on every merge to main.
• You are standardizing API documentation across services and need a neutral, vendor-free composition tool.
• New in 2.6.0: you are on, or planning, Symfony 8 components or a Laravel version that pulls a newer symfony/console. Take the upgrade — the change is a constraint widening only, with no behavioral or API surface change, so it is a very low-risk patch to your locked version.

Look elsewhere when:

• You need a full API governance or docs portal (hosting, versioning, interactive "try it", auth). This merges files; it does not publish or serve them. Pair it with a renderer/portal.
• You need OpenAPI 3.1 merging at the level of JSON Schema 2020-12 semantics — verify support against your target version before committing; merge behavior on 3.1-specific constructs is the main thing to test rather than assume.
• You need semantic conflict resolution — e.g. reconciling two teams that define the same schema name differently. A merger will combine; it will not arbitrate. That's a process decision, not a tooling one.
• Your spec is a single file, or your needs are one-off. A script or an editor is enough; don't add a dependency and a CI stage for a problem you don't have.
• You're not on PHP. The concept (and equivalent tools) exist elsewhere; this specific package is only relevant to a PHP/Laravel toolchain.

Assessment note on the release itself: 2.6.0 is a maintenance release with no new capability, no breaking changes, and no deprecations. On its own it does not change the adoption calculus — it removes a future friction point. Treat it as "keep current," not "re-evaluate."

How to Pitch It (Stakeholders)

To executives (one or two lines): We can publish a single, accurate API specification assembled automatically from the specs each team already writes, instead of paying people to keep one large document in sync by hand. It's a small open-source dependency, not a platform commitment, and the latest version keeps us compatible with our upcoming framework upgrade rather than blocking it.

To engineering (the real case): Each service owns its own OpenAPI fragment; CI merges them into one published spec with marcelthole/openapi-merge and fails the build on invalid input. We stop hand-merging YAML and stop resolving trivial conflicts in review. The cost is one Composer dependency and one CI step; the code is small, the input is plain OpenAPI, and the output is a file — so the exit cost is near zero if it stops fitting. This release is a no-drama dependency bump: it widens the symfony/console constraint to include v8, so it won't hold us back during the Symfony/Laravel upgrade. No behavior changes, no breaking changes — safe to take now.

Risks to flag honestly: low maintenance activity on a small single-maintainer package is the main long-term risk; mitigate by keeping the invocation confined to CI so a swap is a contained change. Also validate behavior against your actual spec versions (3.0 vs 3.1) before making it the publication path for external consumers.