Skip to content

Commit 9420bf5

Browse files
bsaylibsayli
committed
docs(samples): polish docs
1 parent fa467d5 commit 9420bf5

8 files changed

Lines changed: 161 additions & 405 deletions

File tree

‎README.md‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -294,15 +294,15 @@ No migration is required for existing users.
294294

295295
## Key Features
296296

297-
| Feature | What it does | Default |
298-
|----------|--------------|---------|
299-
| **BYOE** — Bring Your Own Envelope | Reuse your existing response envelope (for example `ApiResponse<T>`) instead of `ServiceResponse<T>`. No migration required. | `ServiceResponse<T>` |
300-
| **BYOC** — Bring Your Own Contract | Reuse your existing domain DTOs instead of generating duplicate models. | Generate from spec |
301-
| **Application-defined containers** | Register your own generic container contracts (for example `Paging<T>` or `Window<T>`) and have them participate in the same projection, metadata, and reconstruction pipeline as built-in containers. | Built-in containers only |
302-
| **Container-aware reconstruction** | Deterministically reconstruct built-in and configured generic container types from OpenAPI metadata instead of using container-specific generation logic. | Enabled |
303-
| **Fallback to standard generation** | Disable the generics-aware template patching with a single Maven property. To fully revert to stock OpenAPI Generator behavior, switch the client module to `generatorName=java`. | Generics-aware generation enabled |
304-
| **Deterministic generation** | Apply deterministic template patching, generated-source hygiene, and build-time validation to produce stable, reproducible Java clients. | Enabled |
305-
| **End-to-end samples** | Complete producer, client, and consumer pipelines for Spring Boot 3, Spring Boot 4, `ServiceResponse`, and BYOE scenarios. | See [samples](samples/) |
297+
| Feature | What it does | Default |
298+
|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
299+
| **BYOE** — Bring Your Own Envelope | Reuse your existing response envelope (for example `ApiResponse<T>`) instead of `ServiceResponse<T>`. No migration required. | `ServiceResponse<T>` |
300+
| **BYOC** — Bring Your Own Contract | Reuse your existing domain DTOs instead of generating duplicate models. | Generate from spec |
301+
| **Application-defined containers** | Register your own generic container contracts (for example `Paging<T>` or `Window<T>`) and have them participate in the same projection, metadata, and reconstruction pipeline as built-in containers. | Built-in containers only |
302+
| **Container-aware reconstruction** | Deterministically reconstruct built-in and configured generic container types from OpenAPI metadata instead of using container-specific generation logic. | Enabled |
303+
| **Fallback to standard generation** | Disable the generics-aware template patching with a single Maven property. To fully revert to stock OpenAPI Generator behavior, switch the client module to `generatorName=java`. | Generics-aware generation enabled |
304+
| **Deterministic generation** | Apply deterministic template patching, generated-source hygiene, and build-time validation to produce stable, reproducible Java clients. | Enabled |
305+
| **End-to-end samples** | Complete producer, client, and consumer pipelines for Spring Boot 3, Spring Boot 4, `ServiceResponse`, and BYOE scenarios. | See [samples](samples/) |
306306

307307
---
308308

@@ -397,10 +397,10 @@ To fully revert to stock OpenAPI Generator behavior:
397397
<generatorName>java</generatorName>
398398
```
399399

400-
| `openapi.generics.skip` | Behavior |
401-
|----------|----------|
402-
| `false` (default) | Apply generics-aware template patching |
403-
| `true` | Skip generics-aware template patching |
400+
| `openapi.generics.skip` | Behavior |
401+
|-------------------------|----------------------------------------|
402+
| `false` (default) | Apply generics-aware template patching |
403+
| `true` | Skip generics-aware template patching |
404404

405405
Use this mode for output comparison, troubleshooting, or temporary opt-out scenarios.
406406

@@ -544,13 +544,13 @@ The provided parent configuration includes a tested default, but consumers may o
544544

545545
## Modules
546546

547-
| Module | Responsibility |
548-
|----------|----------------|
549-
| [`openapi-generics-contract`](openapi-generics-contract/README.md) | Shared response contracts and platform-owned generic types. |
550-
| [`openapi-generics-server-starter`](openapi-generics-server-starter/README.md) | Spring Boot integration that projects generic contract metadata into OpenAPI. |
551-
| [`openapi-generics-java-codegen`](openapi-generics-java-codegen/README.md) | OpenAPI Generator specialization that reconstructs contract-aligned Java clients. |
547+
| Module | Responsibility |
548+
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
549+
| [`openapi-generics-contract`](openapi-generics-contract/README.md) | Shared response contracts and platform-owned generic types. |
550+
| [`openapi-generics-server-starter`](openapi-generics-server-starter/README.md) | Spring Boot integration that projects generic contract metadata into OpenAPI. |
551+
| [`openapi-generics-java-codegen`](openapi-generics-java-codegen/README.md) | OpenAPI Generator specialization that reconstructs contract-aligned Java clients. |
552552
| [`openapi-generics-java-codegen-parent`](openapi-generics-java-codegen-parent/README.md) | Maven parent for client generation, template patching, and generated-source hygiene. |
553-
| [`openapi-generics-platform-bom`](openapi-generics-platform-bom/README.md) | Dependency alignment for OpenAPI Generics modules. |
553+
| [`openapi-generics-platform-bom`](openapi-generics-platform-bom/README.md) | Dependency alignment for OpenAPI Generics modules. |
554554

555555
---
556556

‎docs/architecture/architecture.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -161,13 +161,13 @@ Supported capabilities:
161161

162162
## Module Map
163163

164-
| Module | Responsibility |
165-
|------------------------------------------------------------------------------------------------|----------------|
166-
| [`openapi-generics-contract`](../../openapi-generics-contract/README.md) | Shared contracts and platform types |
167-
| [`openapi-generics-server-starter`](../../openapi-generics-server-starter/README.md) | Spring Boot projection pipeline |
168-
| [`openapi-generics-java-codegen`](../../openapi-generics-java-codegen/README.md) | Contract-aware OpenAPI Generator extension |
164+
| Module | Responsibility |
165+
|------------------------------------------------------------------------------------------------|------------------------------------------------|
166+
| [`openapi-generics-contract`](../../openapi-generics-contract/README.md) | Shared contracts and platform types |
167+
| [`openapi-generics-server-starter`](../../openapi-generics-server-starter/README.md) | Spring Boot projection pipeline |
168+
| [`openapi-generics-java-codegen`](../../openapi-generics-java-codegen/README.md) | Contract-aware OpenAPI Generator extension |
169169
| [`openapi-generics-java-codegen-parent`](../../openapi-generics-java-codegen-parent/README.md) | Generator orchestration and template lifecycle |
170-
| [`openapi-generics-platform-bom`](../../openapi-generics-platform-bom/README.md) | Dependency alignment |
170+
| [`openapi-generics-platform-bom`](../../openapi-generics-platform-bom/README.md) | Dependency alignment |
171171

172172
---
173173

‎docs/architecture/rationale.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -86,11 +86,11 @@ These limitations are documented in public issue trackers and reflect the curren
8686

8787
Clear separation of concerns is necessary for accurate analysis:
8888

89-
| Category | Description | Current Relevance to Generic Contract Preservation | Primary Remediation Path |
90-
|---------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------|-------------------------------------------|
91-
| **Specification** | What the OpenAPI and JSON Schema standards define or deliberately omit. | Dynamic references exist; no native generic type parameter syntax. | Future specification work. |
92-
| **Implementation** | Behavior of a specific parser, dereferencer, or generator. | Partial or conservative handling of dynamic references in major implementations. | Contributions to individual projects. |
93-
| **Ecosystem** | Emergent behavior from composition of multiple tools and frameworks. | End-to-end loss of generic relationships across Springdoc → parser → generator paths. | Compatibility layers or coordinated evolution. |
89+
| Category | Description | Current Relevance to Generic Contract Preservation | Primary Remediation Path |
90+
|--------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------|------------------------------------------------|
91+
| **Specification** | What the OpenAPI and JSON Schema standards define or deliberately omit. | Dynamic references exist; no native generic type parameter syntax. | Future specification work. |
92+
| **Implementation** | Behavior of a specific parser, dereferencer, or generator. | Partial or conservative handling of dynamic references in major implementations. | Contributions to individual projects. |
93+
| **Ecosystem** | Emergent behavior from composition of multiple tools and frameworks. | End-to-end loss of generic relationships across Springdoc → parser → generator paths. | Compatibility layers or coordinated evolution. |
9494

9595
This project operates primarily at the ecosystem level. It accepts the current practical state of specification support and core implementation behavior as the baseline for production use and introduces a deterministic layer that works with existing OpenAPI documents.
9696

‎docs/compatibility.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -84,17 +84,17 @@ Configured containers participate in the same projection, metadata enrichment, a
8484
8585
### Runtime — Server-Side Projection
8686
87-
| Java | Spring Boot | springdoc-openapi | Scope | Status |
88-
|---|---|---|---|---|
89-
| 17+ | 3.4.x | 2.8.x | WebMvc | Supported |
90-
| 17+ | 3.5.x | 2.8.x | WebMvc | Supported |
91-
| 17+ | 4.x | 3.x | WebMvc | Supported |
87+
| Java | Spring Boot | springdoc-openapi | Scope | Status |
88+
|------|-------------|-------------------|--------|-----------|
89+
| 17+ | 3.4.x | 2.8.x | WebMvc | Supported |
90+
| 17+ | 3.5.x | 2.8.x | WebMvc | Supported |
91+
| 17+ | 4.x | 3.x | WebMvc | Supported |
9292
9393
### Build-Time — Client Generation
9494
95-
| Java | OpenAPI Generator | Build Tool | Status |
96-
|---|---|---|---|
97-
| 17+ | 7.x | Maven | Supported |
95+
| Java | OpenAPI Generator | Build Tool | Status |
96+
|------|-------------------|------------|-----------|
97+
| 17+ | 7.x | Maven | Supported |
9898
9999
The client generation parent provides a tested default OpenAPI Generator version, but consumers may override `openapi-generator.version` within the supported 7.x line.
100100

‎docs/index.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -142,15 +142,15 @@ openapi-generics:
142142
143143
## Key Features
144144
145-
| Feature | Description |
146-
|----------|-------------|
147-
| **Contract-first** | Java remains the source of truth. |
148-
| **BYOE** | Reuse your own response envelope. |
149-
| **BYOC** | Reuse externally owned DTOs. |
150-
| **Application-defined containers** | Register custom generic containers. |
145+
| Feature | Description |
146+
|------------------------------------|----------------------------------------------------------------------|
147+
| **Contract-first** | Java remains the source of truth. |
148+
| **BYOE** | Reuse your own response envelope. |
149+
| **BYOC** | Reuse externally owned DTOs. |
150+
| **Application-defined containers** | Register custom generic containers. |
151151
| **Container-aware reconstruction** | Built-in and configured containers share one deterministic pipeline. |
152-
| **Deterministic generation** | Stable projection, validation, and generated clients. |
153-
| **Generated-source hygiene** | Cleaner Java imports and generated artifacts. |
152+
| **Deterministic generation** | Stable projection, validation, and generated clients. |
153+
| **Generated-source hygiene** | Cleaner Java imports and generated artifacts. |
154154
155155
---
156156

‎samples/README.md‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,11 @@ The generated client reconstructs the original contract shape instead of redefin
4242

4343
Each runnable integration stack contains three layers:
4444

45-
| Layer | Responsibility |
46-
|----------|----------------|
47-
| **Producer** | Defines the Java API contract and publishes the OpenAPI document. |
48-
| **Generated client** | Is generated from the OpenAPI document using OpenAPI Generics. |
49-
| **Consumer** | Uses the generated client and exposes downstream verification endpoints. |
45+
| Layer | Responsibility |
46+
|----------------------|--------------------------------------------------------------------------|
47+
| **Producer** | Defines the Java API contract and publishes the OpenAPI document. |
48+
| **Generated client** | Is generated from the OpenAPI document using OpenAPI Generics. |
49+
| **Consumer** | Uses the generated client and exposes downstream verification endpoints. |
5050

5151
The same contract moves through all layers.
5252

@@ -74,22 +74,22 @@ samples
7474
└── byoe-response
7575
```
7676

77-
| Directory | Purpose |
78-
|----------|---------|
79-
| `domain-contracts` | Shared domain and contract types used by the sample stacks. |
80-
| `spring-boot-3` | Runnable Spring Boot 3 producer → generated client → consumer stack. |
81-
| `spring-boot-4` | Runnable Spring Boot 4 producer → generated client → consumer stack. |
82-
| `type-coverage` | Focused validation suites for supported generic response shapes and regression coverage. |
77+
| Directory | Purpose |
78+
|--------------------|------------------------------------------------------------------------------------------|
79+
| `domain-contracts` | Shared domain and contract types used by the sample stacks. |
80+
| `spring-boot-3` | Runnable Spring Boot 3 producer → generated client → consumer stack. |
81+
| `spring-boot-4` | Runnable Spring Boot 4 producer → generated client → consumer stack. |
82+
| `type-coverage` | Focused validation suites for supported generic response shapes and regression coverage. |
8383

8484
---
8585

8686
## Available Sample Types
8787

8888
The repository contains two kinds of samples.
8989

90-
| Sample Type | Purpose |
91-
|------------|---------|
92-
| **Integration stacks** | Runnable producer → generated client → consumer applications for Spring Boot 3 and Spring Boot 4. |
90+
| Sample Type | Purpose |
91+
|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
92+
| **Integration stacks** | Runnable producer → generated client → consumer applications for Spring Boot 3 and Spring Boot 4. |
9393
| **Type coverage samples** | Focused regression suites that validate supported generic response shapes, BYOE contracts, collections, pages, and application-owned generic containers. |
9494

9595
The integration stacks are intended for first-time users who want to run the platform end-to-end.
@@ -130,9 +130,9 @@ Spring Boot 3 Consumer
130130

131131
### Services
132132

133-
| Service | Port | URL |
134-
|---------|------|-----|
135-
| Producer | 8084 | `http://localhost:8084/customer-service` |
133+
| Service | Port | URL |
134+
|----------|------|---------------------------------------------------|
135+
| Producer | 8084 | `http://localhost:8084/customer-service` |
136136
| Consumer | 8085 | `http://localhost:8085/customer-service-consumer` |
137137

138138
### Start
@@ -204,9 +204,9 @@ Spring Boot 4 Consumer
204204

205205
### Services
206206

207-
| Service | Port | URL |
208-
|---------|------|-----|
209-
| Producer | 8094 | `http://localhost:8094/customer-service` |
207+
| Service | Port | URL |
208+
|----------|------|---------------------------------------------------|
209+
| Producer | 8094 | `http://localhost:8094/customer-service` |
210210
| Consumer | 8095 | `http://localhost:8095/customer-service-consumer` |
211211

212212
### Start
@@ -281,10 +281,10 @@ They verify contract-preservation behavior across supported response shapes, inc
281281

282282
Available type-coverage samples:
283283

284-
| Sample | Purpose |
285-
|----------|----------|
286-
| `type-coverage/service-response` | Validates the canonical platform-provided `ServiceResponse<T>` contract. |
287-
| `type-coverage/byoe-response` | Validates Bring Your Own Envelope support using a user-owned `ApiResponse<T>` contract. |
284+
| Sample | Purpose |
285+
|----------------------------------|-----------------------------------------------------------------------------------------|
286+
| `type-coverage/service-response` | Validates the canonical platform-provided `ServiceResponse<T>` contract. |
287+
| `type-coverage/byoe-response` | Validates Bring Your Own Envelope support using a user-owned `ApiResponse<T>` contract. |
288288

289289
These samples are used as executable regression suites for projection metadata, vendor extensions, wrapper reconstruction, generated client typing, runtime deserialization, and consumer compatibility.
290290

0 commit comments

Comments
 (0)