feat(server): support application-defined generic containers

[bsayli]

🧩 Pull Request

🎯 Summary

This PR introduces support for application-defined generic containers in the server-side projection pipeline.

Applications can now register their own generic container contracts (for example Paging<T> or Window<T>) through configuration. Once validated at startup, these containers participate in the same introspection, projection, metadata generation, and reconstruction lifecycle as the built-in List, Set, and Page containers.

---

📦 Changes

• Added configuration support for custom generic containers.
• Introduced a unified container descriptor model for built-in and configured containers.
• Added startup validation for configured container contracts.
• Unified container resolution across response introspection and schema enrichment.
• Extended projection metadata to preserve container identity (x-data-container-type).
• Expanded unit and type-coverage tests for configurable containers.
• Added sample applications demonstrating Paging<T> and Window<T> containers.

---

🧠 Outcome / Impact

• Enables application-owned generic containers without platform modifications.
• Removes the need for container-specific platform implementations.
• Preserves deterministic projection and reconstruction behavior.
• Unifies built-in and configured containers under a single metadata pipeline.
• Improves extensibility while remaining fully backward compatible.

---

🔐 Contract Awareness

Contract impact: yes

Affected areas:

• OpenAPI projection metadata
• Vendor extension vocabulary (x-data-container-type)
• Container metadata generation
• Response introspection pipeline

Existing response contracts (ServiceResponse<T>, List, Set, Page) remain fully compatible.

---

🌍 Multi-Language Considerations

The additional vendor extension is ignored by generators that do not recognize it and therefore remains a no-op outside OpenAPI Generics.

Java reconstruction benefits from preserving the fully qualified container type while maintaining compatibility with existing generated specifications.

---

🧱 Affected Layer

• Contract (openapi-generics-contract)
• Projection (openapi-generics-server-starter)
• Generator (openapi-generics-java-codegen)
• Generator Parent (openapi-generics-java-codegen-parent)
• Build / CI
• Documentation

---

🔄 Dependency Path Impact

Server path:

server-starter → contract

No client-side dependency changes.

---

✅ Checklist

• Scope is minimal and focused
• Build passes: mvn -q -ntp clean verify
• Tests added/updated
• Docs updated where behavior changed
• Contract impact evaluated
• No direct edits to generated code
• Changes applied at the projection layer
• Linked issue: Support application-defined generic containers #29

---

🧾 Metadata

• Type: feature
• Related Issue: Support application-defined generic containers #29
• Target Release: 1.2.0