# Reflection‑First Strategy for Generics Detection (KISS Principle)

[bsayli]

Reflection‑First Strategy for Generics Detection (KISS Principle)

Category: Ideas
Tags: openapi, spring-boot, springdoc, java, generics, codegen, contracts

TL;DR
Generics-aware OpenAPI does not require configuration, annotations, or schema duplication.
With a canonical contract as authority and reflection as the discovery mechanism, the system becomes deterministic end-to-end.

---

📑 Table of Contents

• Context

• Current Direction — Contract + Reflection

  • Controller Inspection
  • Generic Resolution
  • Container Semantics
  • Safety & Determinism

• Why No Configuration?

• Generic Depth Policy

• Projection Boundary (Critical)

• Generator Boundary (Critical)

• Architectural Guarantees

• Summary

---

Context

This platform follows a strict rule:

Java contract is the single source of truth (SSOT).

The canonical contract is defined in:

openapi-generics-contract

It owns:

• ServiceResponse<T> — success envelope
• Page<T>, Meta, Sort — pagination
• RFC 9457 extensions — error model

All other layers:

• server (Spring Boot)
• OpenAPI (projection)
• generator (code emission)

are derived from this contract, not independent authorities.

---

Current Direction — Contract + Reflection

The system uses reflection only, but within a strict architectural boundary:

• reflection discovers types
• contract defines meaning
• projection encodes metadata
• generator consumes metadata

---

1️⃣ Controller Inspection

At runtime, controller methods are inspected.

Return types are unwrapped until the contract boundary is reached.

Supported wrappers (non-exhaustive):

• ResponseEntity<T>
• CompletionStage<T>
• DeferredResult<T>

Unwrapping stops at:

ServiceResponse<...>

---

2️⃣ Generic Resolution

Using ResolvableType, the system resolves:

• root envelope → ServiceResponse
• inner type → T
• optional container → Page<T>

Supported depths:

Depth	Example	Supported
1	ServiceResponse<CustomerDto>	✅ Yes
2	ServiceResponse<Page<CustomerDto>>	✅ Yes
3+	deeper nesting	❌ No

This is a design constraint, not a limitation.

---

3️⃣ Container Semantics

Containers are not inferred arbitrarily.

They are recognized only if defined in the contract.

Example:

• Page<T> → recognized
• custom unknown containers → ignored

Projection enriches schema with metadata:

x-api-wrapper: true
x-data-container: Page
x-data-item: CustomerDto

No metadata is added if resolution is uncertain.

---

4️⃣ Safety & Determinism

System guarantees:

• bounded unwrap depth
• no schema generation failures
• graceful fallback for unknown types

Key rule:

If something is not known with certainty, it is not projected.

---

Why No Configuration?

Because configuration introduces duplication.

• annotations duplicate method signatures
• YAML allow-lists drift
• switches break determinism

With a canonical contract:

• all required information already exists
• reflection is sufficient
• behavior is reproducible

---

Generic Depth Policy

Only one level of nesting is allowed:

ServiceResponse<Page<T>>

This ensures:

• readable OpenAPI
• simple generator templates
• stable naming

---

Projection Boundary (Critical)

OpenAPI is a projection layer.

It:

• carries metadata (vendor extensions)
• represents contract structure

It does not:

• define behavior
• own the contract
• introduce new semantics

---

Generator Boundary (Critical)

Generator responsibility is minimal:

• bind generic parameters
• create thin wrapper classes

It does not:

• define envelopes
• change inheritance
• reinterpret schema

Example:

class CustomerPageResponse extends ServiceResponse<Page<CustomerDto>> {}

All semantics come from the contract module.

---

Architectural Guarantees

This architecture guarantees:

• single contract authority
• deterministic OpenAPI output
• stable client generation
• no envelope duplication
• no cross-layer drift

---

Summary

This approach proves:

• reflection is enough when contract is authoritative
• projection must be lossless and deterministic
• generation must be minimal and predictable

No annotations. No YAML. No configuration.

Only:

• contract (authority)
• projection (OpenAPI)
• generation (code)

---

Architecture becomes clear when each layer is allowed to do only one thing.

[bsayli]

This discussion reflects an early design stage of the project.

The architecture described here was superseded by the container-aware infrastructure introduced in OpenAPI Generics 1.1.0.

Current capabilities include:

• generic container metadata model
• List support
• Set support
• Page support
• BYOE container support
• deterministic projection and reconstruction

For current architecture and supported capabilities, refer to the latest documentation.