test(samples): add transport compatibility coverage

Author: bsayli

CHANGELOG.md

@@ -16,14 +16,15 @@ This project follows a contract-first release discipline:
 
 OpenAPI Generics 1.2.1 simplifies contract-driven wrapper reconstruction by making the generated OpenAPI document the single source of truth for envelope identity.
 
-This release removes redundant client-side envelope configuration, completes end-to-end validation for application-defined generic containers with the built-in `ServiceResponse<T>` envelope, and continues platform verification and dependency alignment without changing runtime behavior.
+This release removes redundant client-side envelope configuration, completes end-to-end validation for application-defined generic containers with the built-in `ServiceResponse<T>` envelope, and expands platform verification across contract reconstruction, framework compatibility, and standard HTTP transport behavior without changing runtime behavior.
 
 ### Added
 
 - Added the `x-api-wrapper-type` vendor extension to preserve the fully qualified Java envelope type in projected wrapper schemas.
 - Added contract-driven envelope reconstruction in the Java code generator based on `x-api-wrapper-type`.
 - Added end-to-end validation for application-defined generic containers used with the built-in `ServiceResponse<T>` envelope.
 - Expanded sample coverage for producer → OpenAPI → generated client → consumer validation using application-owned generic containers.
+- Added a dedicated `transport-coverage` sample for multipart upload, binary download, and form-urlencoded compatibility with the Java RestClient generator.
 
 ### Changed
 
@@ -44,6 +45,11 @@ This release removes redundant client-side envelope configuration, completes end
 - Added verification that generated clients reconstruct wrapper inheritance without client-side envelope configuration.
 - Verified built-in `ServiceResponse<T>` and BYOE envelope generation using the same metadata-driven reconstruction pipeline.
 - Verified producer → OpenAPI → generated client → consumer flows after removing redundant client-side envelope configuration.
+- Added transport regression coverage for `multipart/form-data`, `application/octet-stream`, and `application/x-www-form-urlencoded`.
+- Verified that standard OpenAPI Generator Java RestClient transport behavior remains intact while generic JSON response reconstruction is enabled.
+- Verified multipart file plus structured JSON part generation together with `ServiceResponse<T>` reconstruction.
+- Verified binary download generation using the standard Spring `Resource` abstraction without wrapper interference.
+- Verified form-urlencoded request generation together with generic response reconstruction.
 - Verified the Spring Boot 4 integration stack on Spring Boot 4.1.0, Springdoc 3.1.0, and Java 25 LTS.
 - Verified mixed Java baselines with Java 21 for Spring Boot 3 samples and Java 25 for Spring Boot 4 samples while published platform artifacts continue targeting Java 17+.
 

samples/README.md

@@ -20,8 +20,6 @@ Consumer Service
 
 The generated client reconstructs the original contract shape instead of redefining equivalent wrapper models.
 
----
-
 ## Table of Contents
 
 - [Overview](#overview)
@@ -31,31 +29,28 @@ The generated client reconstructs the original contract shape instead of redefin
 - [Spring Boot 3 Stack](#spring-boot-3-stack)
 - [Spring Boot 4 Stack](#spring-boot-4-stack)
 - [Type Coverage Samples](#type-coverage-samples)
+- [Transport Coverage Sample](#transport-coverage-sample)
 - [Local Maven Build](#local-maven-build)
 - [What to Observe](#what-to-observe)
 - [Notes](#notes)
 - [Summary](#summary)
 
----
-
 ## Overview
 
 Each runnable integration stack contains three layers:
 
-| Layer                | Responsibility                                                           |
-|----------------------|--------------------------------------------------------------------------|
-| **Producer**         | Defines the Java API contract and publishes the OpenAPI document.        |
-| **Generated client** | Is generated from the OpenAPI document using OpenAPI Generics.           |
-| **Consumer**         | Uses the generated client and exposes downstream verification endpoints. |
+| Layer | Responsibility |
+| --- | --- |
+| **Producer** | Defines the Java API contract and publishes the OpenAPI document. |
+| **Generated client** | Is generated from the OpenAPI document using OpenAPI Generics. |
+| **Consumer** | Uses the generated client and exposes downstream verification endpoints. |
 
 The same contract moves through all layers.
 
 No manual wrapper reconstruction is required in the consumer.
 
 No DTO translation layer is required between producer and consumer.
 
----
-
 ## Sample Layout
 
 ```text
@@ -69,34 +64,35 @@ samples
 │   ├── customer-service
 │   ├── customer-service-client
 │   └── customer-service-consumer
-└── type-coverage
-    ├── service-response
-    └── byoe-response
+├── type-coverage
+│   ├── service-response
+│   └── byoe-response
+└── transport-coverage
 ```
 
-| Directory          | Purpose                                                                                  |
-|--------------------|------------------------------------------------------------------------------------------|
-| `domain-contracts` | Shared domain and contract types used by the sample stacks.                              |
-| `spring-boot-3`    | Runnable Spring Boot 3 producer → generated client → consumer stack.                     |
-| `spring-boot-4`    | Runnable Spring Boot 4 producer → generated client → consumer stack.                     |
-| `type-coverage`    | Focused validation suites for supported generic response shapes and regression coverage. |
-
----
+| Directory | Purpose |
+| --- | --- |
+| `domain-contracts` | Shared domain and contract types used by the sample stacks. |
+| `spring-boot-3` | Runnable Spring Boot 3 producer → generated client → consumer stack. |
+| `spring-boot-4` | Runnable Spring Boot 4 producer → generated client → consumer stack. |
+| `type-coverage` | Focused validation suites for supported generic response shapes and regression coverage. |
+| `transport-coverage` | Focused validation suite for transport compatibility and regression coverage. |
 
 ## Available Sample Types
 
-The repository contains two kinds of samples.
+The repository contains three kinds of samples.
 
-| Sample Type               | Purpose                                                                                                                                                  |
-|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Integration stacks**    | Runnable producer → generated client → consumer applications for Spring Boot 3 and Spring Boot 4.                                                        |
-| **Type coverage samples** | Focused regression suites that validate supported generic response shapes, BYOE contracts, collections, pages, and application-owned generic containers. |
+| Sample Type | Purpose |
+| --- | --- |
+| **Integration stacks** | Runnable producer → generated client → consumer applications for Spring Boot 3 and Spring Boot 4. |
+| **Type coverage samples** | Focused regression suites validating generic response reconstruction across supported contract shapes. |
+| **Transport coverage sample** | Focused regression suite validating standard HTTP transport compatibility together with generic response reconstruction. |
 
 The integration stacks are intended for first-time users who want to run the platform end-to-end.
 
-The type coverage samples are intended for validating the core OpenAPI Generics reconstruction pipeline across many response shapes.
+The type-coverage samples validate the core OpenAPI Generics reconstruction pipeline across many response shapes.
 
----
+The transport-coverage sample validates that the custom `java-generics-contract` generator remains compatible with standard OpenAPI Generator transport behavior.
 
 ## Prerequisites
 
@@ -107,10 +103,12 @@ For Docker-based sample execution:
 
 For local Maven builds:
 
-- Java 17+
+- Java 25
 - Maven 3.9+
 
----
+The sample suite includes both Java 21 and Java 25 modules. Building the complete `samples` reactor therefore requires JDK 25.
+
+Published OpenAPI Generics platform artifacts continue to target Java 17+.
 
 ## Spring Boot 3 Stack
 
@@ -130,15 +128,13 @@ Spring Boot 3 Consumer
 
 ### Services
 
-| Service  | Port | URL                                               |
-|----------|------|---------------------------------------------------|
-| Producer | 8084 | `http://localhost:8084/customer-service`          |
-| Consumer | 8085 | `http://localhost:8085/customer-service-consumer` |
+| Service | Port |
+| --- | ---: |
+| Producer | 8084 |
+| Consumer | 8085 |
 
 ### Start
 
-From the `samples` directory:
-
 ```bash
 cd spring-boot-3
 docker compose up --build -d
@@ -160,14 +156,10 @@ http://localhost:8084/customer-service/swagger-ui/index.html
 
 ### Verify Consumer
 
-Single resource:
-
 ```bash
 curl http://localhost:8085/customer-service-consumer/customers/1
 ```
 
-Paginated response:
-
 ```bash
 curl "http://localhost:8085/customer-service-consumer/customers?page=0&size=5"
 ```
@@ -178,19 +170,15 @@ The response should preserve the same contract shape across producer, OpenAPI, g
 
 ### Stop
 
-From the `samples/spring-boot-3` directory:
-
 ```bash
 docker compose down
 ```
 
----
-
 ## Spring Boot 4 Stack
 
 Use this stack when validating the Spring Boot 4 runtime path.
 
-It runs the same OpenAPI Generics lifecycle as the Spring Boot 3 stack, but on the Spring Boot 4 baseline:
+It runs the same lifecycle:
 
 ```text
 Spring Boot 4 Producer
@@ -204,15 +192,13 @@ Spring Boot 4 Consumer
 
 ### Services
 
-| Service  | Port | URL                                               |
-|----------|------|---------------------------------------------------|
-| Producer | 8094 | `http://localhost:8094/customer-service`          |
-| Consumer | 8095 | `http://localhost:8095/customer-service-consumer` |
+| Service | Port |
+| --- | ---: |
+| Producer | 8094 |
+| Consumer | 8095 |
 
 ### Start
 
-From the `samples` directory:
-
 ```bash
 cd spring-boot-4
 docker compose up --build -d
@@ -234,79 +220,83 @@ http://localhost:8094/customer-service/swagger-ui/index.html
 
 ### Verify Consumer
 
-Single resource:
-
 ```bash
 curl http://localhost:8095/customer-service-consumer/customers/1
 ```
 
-Paginated response:
-
 ```bash
 curl "http://localhost:8095/customer-service-consumer/customers?page=0&size=5"
 ```
 
 The behavior is intentionally equivalent to the Spring Boot 3 stack.
 
-The purpose is to verify that the same OpenAPI Generics contract flow works across the Spring Boot 4 runtime baseline.
-
 ### Stop
 
-From the `samples/spring-boot-4` directory:
-
 ```bash
 docker compose down
 ```
 
----
-
 ## Type Coverage Samples
 
 The `type-coverage` directory contains focused validation suites for the core OpenAPI Generics reconstruction pipeline.
 
 Unlike the Spring Boot integration stacks, these samples are not intended to demonstrate application architecture or business workflows.
 
-They verify contract-preservation behavior across supported response shapes, including:
+They validate contract preservation across supported response shapes, including:
 
 - scalar payloads
 - value payloads
 - enum payloads
 - DTO payloads
-- `List<T>` payloads
-- `Set<T>` payloads
-- built-in `Page<T>` payloads
-- application-owned generic containers such as `Paging<T>` and `Window<T>`
-- platform-owned `ServiceResponse<T>` envelopes
-- user-owned BYOE `ApiResponse<T>` envelopes
+- `List<T>`
+- `Set<T>`
+- built-in `Page<T>`
+- application-owned generic containers
+- platform-owned `ServiceResponse<T>`
+- user-owned BYOE `ApiResponse<T>`
 
-Available type-coverage samples:
+Available samples:
 
-| Sample                           | Purpose                                                                                 |
-|----------------------------------|-----------------------------------------------------------------------------------------|
-| `type-coverage/service-response` | Validates the canonical platform-provided `ServiceResponse<T>` contract.                |
-| `type-coverage/byoe-response`    | Validates Bring Your Own Envelope support using a user-owned `ApiResponse<T>` contract. |
+| Sample | Purpose |
+| --- | --- |
+| `type-coverage/service-response` | Validates the platform-provided `ServiceResponse<T>` contract. |
+| `type-coverage/byoe-response` | Validates Bring Your Own Envelope using a user-owned `ApiResponse<T>` contract. |
 
-These samples are used as executable regression suites for projection metadata, vendor extensions, wrapper reconstruction, generated client typing, runtime deserialization, and consumer compatibility.
+See [`type-coverage/README.md`](type-coverage/README.md) for the complete validation matrix.
 
-See [`type-coverage/README.md`](type-coverage/README.md) for the full validation matrix.
+## Transport Coverage Sample
 
----
+The `transport-coverage` directory validates that OpenAPI Generics remains transport-neutral.
 
-## Local Maven Build
+Rather than introducing new transport behavior, it verifies that the custom `java-generics-contract` generator preserves the standard transport functionality provided by the upstream Java RestClient generator.
+
+The initial transport matrix covers:
 
-Docker is the recommended path for running the integration stacks.
+- `multipart/form-data`
+- `application/octet-stream`
+- `application/x-www-form-urlencoded`
 
-For local build verification, run from the `samples` directory:
+while simultaneously validating generic response reconstruction where JSON responses are returned.
+
+Available sample:
+
+| Sample | Purpose |
+| --- | --- |
+| `transport-coverage` | Validates transport compatibility together with generic response reconstruction. |
+
+See [`transport-coverage/README.md`](transport-coverage/README.md) for transport scenarios, validation flow, and regression scope.
+
+## Local Maven Build
+
+From the `samples` directory:
 
 ```bash
 mvn clean install
 ```
 
-This builds the sample modules and verifies that generated client artifacts compile successfully.
-
-Individual services can also be started locally from their module directories when needed.
+This builds every sample module and verifies that generated client artifacts compile successfully.
 
----
+Individual services can also be started directly from their module directories when needed.
 
 ## What to Observe
 
@@ -324,7 +314,7 @@ Observe that:
 - paginated generic responses keep their generic structure
 - generated wrappers extend reusable contract types instead of redefining equivalent models
 
-For example, generated response wrappers should remain thin contract bindings rather than duplicated envelope implementations:
+For example:
 
 ```java
 public class ServiceResponsePageCustomerDto
@@ -335,25 +325,26 @@ The generated class binds the generic parameters.
 
 It does not become the owner of the envelope structure.
 
----
-
 ## Notes
 
 - Samples use in-memory data.
 - No external database is required.
 - The sample domain is intentionally simple.
-- The focus is contract projection, generated client reconstruction, and downstream reuse.
 - Spring Boot 3 and Spring Boot 4 stacks are intentionally equivalent.
-- Type-coverage samples provide focused regression validation beyond the customer-service integration flow.
-- You do not need to run the Spring Boot 3 and Spring Boot 4 stacks at the same time.
-
----
+- Type-coverage samples validate generic reconstruction across supported contract shapes.
+- Transport-coverage validates compatibility with standard OpenAPI Generator transport behavior.
+- You do not need to run every sample simultaneously.
 
 ## Summary
 
 These samples provide runnable environments for validating the OpenAPI Generics contract lifecycle.
 
-They prove that a Java contract can be projected into OpenAPI, reconstructed into a generated Java client, and reused by a downstream consumer without redefining equivalent wrapper or DTO models.
+Together they demonstrate:
+
+- end-to-end producer → generated client → consumer integration
+- generic response reconstruction
+- Bring Your Own Envelope (BYOE)
+- transport compatibility with standard OpenAPI Generator behavior
 
 ```text
 Java Contract
@@ -365,4 +356,4 @@ Generated Client
 Consumer Reuse
 ```
 
-The result is stable contract identity across service boundaries.
+The result is stable contract identity across service boundaries while preserving both generic semantics and standard transport behavior.

samples/pom.xml

@@ -30,6 +30,7 @@
         <module>spring-boot-3</module>
         <module>spring-boot-4</module>
         <module>type-coverage</module>
+        <module>transport-coverage</module>
     </modules>
     <build>
         <pluginManagement>