Api Resource Bundle Laravel Package

Product Decisions This Supports

• API contract governance as a build-time gate. v2.2.0 extends the scaffolded #[ApiProperty(description: '')] convention from DTOs (2.1.0) down to the filter layer: every generated QueryParameter in an <Entity>Filters catalog now carries an explicit description argument, left empty for product/front to fill. The paired application-side architecture test that rejects an empty description turns documentation from a launch-week afterthought into a merge-blocking requirement. This is a lever for deciding whether OpenAPI/API docs are a shipped artifact or a best-effort artifact.
• Roadmap sequencing for API surface work. The scaffold deliberately emits empty strings rather than invented copy, which cleanly separates generation (package) from authoring (product/front per the feuille de route). This supports planning a documentation pass as a distinct, estimable workstream that lands before exposure, not after.
• Build vs buy on internal scaffolding. The value here is cumulative convention enforcement (DTOs in 2.1.0 → filters in 2.2.0 → architecture test). Re-implementing this in-house means owning both the generator and the guardrail, plus re-deriving the exemption list (status, realm as framework-level system parameters). Buying/inheriting keeps one team's opinions about what counts as a "documented" parameter.
• Scoping exemptions as a product call. Exempting status and realm encodes a judgment: system-owned, universally understood parameters don't need bespoke prose. That is a policy decision worth reviewing explicitly — it is where the package makes a stance the team may or may not share.
• Use cases: internal admin/back-office APIs where filter catalogs are numerous and uniform; CRUD-heavy domains with many entities where manual filter documentation does not scale; teams already standardizing on attribute-driven API metadata (attribute-based OpenAPI generators, static analysis tooling).

When to Consider This Package

Adopt when:

• You generate entity filters and DTOs rather than hand-writing them, and the generator already produces the shape you want — the incremental cost here is a description argument plus one test.
• You are willing to enforce the architecture test in CI. Without the test, this release is inert: you get empty-string placeholders that nobody is compelled to fill, and worse, an API that appears documented because the field exists.
• Your team can commit to a description authoring workflow (who writes French copy, from what source, at what point in the entity lifecycle). The release assumes a "feuille de route front" exists; if no such artifact does, the empty placeholders accumulate as debt.
• You have a small, stable set of non-documented system parameters, so the status/realm exemption is not the thin end of an ever-growing allowlist.

Look elsewhere or defer when:

• Your API documentation lives in a source of truth other than PHP attributes (hand-written OpenAPI, a design-first spec, a gateway config). Regenerating descriptions into code duplicates that source and will drift.
• You have a single-locale product and no requirement for French-authored descriptions specifically — the localization assumption baked into the release notes may not match your copy pipeline.
• You cannot tolerate a hard CI failure on undocumented filters; a soft lint warning is a different product decision, and this package does not offer it.
• You are not on the 2.1.0 DTO convention. This release explicitly prolongs that scaffold; adopting 2.2.0 without it gives an inconsistent surface.

How to Pitch It (Stakeholders)

For executives: This release makes API documentation a precondition of shipping rather than a follow-up task. Every generated filter parameter must now carry a description, and the build fails until someone writes it. Cost is low and localized — one argument in a generator, one test — but the strategic effect is that undocumented endpoints cannot silently reach customers. Treat it as a policy commitment, not a feature: the value is realized only if we enforce the test and staff the copy review.

For engineering: No breaking changes. Generated <Entity>Filters now emit QueryParameter(..., description: '') on every parameter; status and realm are exempted as framework-level. The app-side architecture test must be adopted in the same release, otherwise the placeholders are decorative. Two things to settle before rollout: (1) the mechanism for filling descriptions — regenerate-and-edit is fragile if the generator overwrites, so confirm generated catalogs are either user-owned post-generation or the descriptions live in a side channel the generator reads; (2) the exemption list is now a maintained surface — each new exemption should require review, or the guarantee erodes quietly. French copy is assumed; flag if that is wrong for any consuming service.