docs(site): restructure navigation with adoption guides

- Added adoption/index.md as parent section
- Linked Server-Side and Client-Side guides under Adoption Guides
- Updated index.md to reference new navigation hierarchy
- Ensured menu ordering with nav_order and parent attributes

Author: barissayli

customer-service-client/README.md

@@ -498,6 +498,7 @@ It enqueues responses for **all CRUD operations** and asserts correct mapping in
 ---
 
 ### Optional: Extra Class Annotations
+
 *(⚙️ advanced feature — use only if needed)*
 
 The generator also supports an **optional vendor extension** to attach annotations directly on top of the generated

customer-service/README.md

@@ -229,7 +229,8 @@ mvn test
 * Focused on clarity and minimal setup.
 * Optional: You can attach extra annotations (e.g., Jackson) to generated wrapper classes by setting  
   `app.openapi.wrapper.class-extra-annotation` in `application.yml`.  
-  See [customer-service-client README](../customer-service-client/README.md#optional-extra-class-annotations) for details.
+  See [customer-service-client README](../customer-service-client/README.md#optional-extra-class-annotations) for
+  details.
 
 ---
 

docs/adoption/client-side-adoption-pom.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Client-Side Build Setup (Maven Plugins & Dependencies)
+parent: Client-Side Adoption
+nav_order: 1
+---
+
 # Client-Side Build Setup (Maven Plugins & Dependencies)
 
 When adopting the **generics-aware OpenAPI client**, make sure to configure your `pom.xml` with the required plugins and
@@ -53,7 +60,22 @@ Add these dependencies to your client module:
 
 ---
 
-## 2) Maven Plugins
+## 2) Maven Properties
+
+Add these properties at the top level of your `pom.xml` (right under `<project>`), so that plugin versions and template
+paths are resolved correctly:
+
+```xml
+<properties>
+    <openapi.generator.version>7.16.0</openapi.generator.version>
+    <openapi.templates.upstream>${project.build.directory}/openapi-templates-upstream</openapi.templates.upstream>
+    <openapi.templates.effective>${project.build.directory}/openapi-templates-effective</openapi.templates.effective>
+</properties>
+```
+
+---
+
+## 3) Maven Plugins
 
 These plugins **work together** to unpack upstream templates, overlay your custom Mustache files, and generate type-safe
 client code.
@@ -189,7 +211,7 @@ client code.
 
 ---
 
-## 3) Why These Plugins Matter
+## 4) Why These Plugins Matter
 
 * **maven-dependency-plugin** → unpacks stock OpenAPI templates.
 * **maven-resources-plugin** → overlays your custom Mustache files.

docs/adoption/index.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Adoption Guides
+nav_order: 2
+has_children: true
+permalink: /adoption/
+---
+
+# 📘 Adoption Guides
+
+Choose one of the following:
+
+- [Server-Side Adoption](server-side-adoption.md)
+- [Client-Side Adoption](client-side-adoption.md)

docs/adoption/server-side-adoption.md

@@ -34,37 +34,38 @@ After this guide, your service will:
 ## 2) Add dependencies (pom.xml)
 
 ```xml
+
 <dependencies>
-  <!-- Web + Bean Validation -->
-  <dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-web</artifactId>
-  </dependency>
-  <dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-validation</artifactId>
-  </dependency>
-
-  <!-- Springdoc (OpenAPI 3.1 + Swagger UI) -->
-  <dependency>
-    <groupId>org.springdoc</groupId>
-    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
-    <version>2.8.13</version>
-  </dependency>
-
-  <!-- optional: configuration processor for metadata hints -->
-  <dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-configuration-processor</artifactId>
-    <optional>true</optional>
-  </dependency>
-
-  <!-- test (optional) -->
-  <dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-test</artifactId>
-    <scope>test</scope>
-  </dependency>
+    <!-- Web + Bean Validation -->
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-validation</artifactId>
+    </dependency>
+
+    <!-- Springdoc (OpenAPI 3.1 + Swagger UI) -->
+    <dependency>
+        <groupId>org.springdoc</groupId>
+        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+        <version>2.8.13</version>
+    </dependency>
+
+    <!-- optional: configuration processor for metadata hints -->
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-configuration-processor</artifactId>
+        <optional>true</optional>
+    </dependency>
+
+    <!-- test (optional) -->
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-test</artifactId>
+        <scope>test</scope>
+    </dependency>
 </dependencies>
 ```
 
@@ -82,22 +83,28 @@ Add your usual build plugins (compiler, surefire/failsafe, jacoco) as you prefer
 **`common/api/response/ServiceResponse.java`**
 
 ```java
-package <your.base>.common.api.response;
+package
+
+<your.base>.common.api.response;
 
 import java.util.Collections;
 import java.util.List;
+
 import org.springframework.http.HttpStatus;
 
 public record ServiceResponse<T>(int status, String message, T data, List<ErrorDetail> errors) {
     public static <T> ServiceResponse<T> ok(T data) {
         return new ServiceResponse<>(HttpStatus.OK.value(), "OK", data, Collections.emptyList());
     }
+
     public static <T> ServiceResponse<T> of(HttpStatus status, String message, T data) {
         return new ServiceResponse<>(status.value(), message, data, Collections.emptyList());
     }
+
     public static <T> ServiceResponse<T> error(HttpStatus status, String message) {
         return new ServiceResponse<>(status.value(), message, null, Collections.emptyList());
     }
+
     public static <T> ServiceResponse<T> error(HttpStatus status, String message, List<ErrorDetail> errors) {
         return new ServiceResponse<>(status.value(), message, null, errors != null ? errors : Collections.emptyList());
     }
@@ -209,36 +216,40 @@ public class SwaggerResponseCustomizer {
 **`ApiResponseSchemaFactory.java`** — builds a *composed* wrapper per concrete `T` (e.g., `CustomerDto`).
 
 ```java
-package <your.base>.common.openapi;
+package
+
+<your.base>.common.openapi;
 
 import static <your.base>.common.openapi.OpenApiSchemas.*;
 
 import io.swagger.v3.oas.models.media.ComposedSchema;
 import io.swagger.v3.oas.models.media.ObjectSchema;
 import io.swagger.v3.oas.models.media.Schema;
+
 import java.util.List;
 
 public final class ApiResponseSchemaFactory {
-  private ApiResponseSchemaFactory() {}
+    private ApiResponseSchemaFactory() {
+    }
 
-  public static Schema<?> createComposedWrapper(String dataRefName) {
-    return createComposedWrapper(dataRefName, null);
-  }
+    public static Schema<?> createComposedWrapper(String dataRefName) {
+        return createComposedWrapper(dataRefName, null);
+    }
 
-  public static Schema<?> createComposedWrapper(String dataRefName, String classExtraAnnotation) {
-    var schema = new ComposedSchema();
-    schema.setAllOf(List.of(
-      new Schema<>().$ref("#/components/schemas/" + SCHEMA_SERVICE_RESPONSE),
-      new ObjectSchema().addProperty(PROP_DATA, new Schema<>().$ref("#/components/schemas/" + dataRefName))
-    ));
-
-    schema.addExtension(EXT_API_WRAPPER, true);
-    schema.addExtension(EXT_API_WRAPPER_DATATYPE, dataRefName);
-    if (classExtraAnnotation != null && !classExtraAnnotation.isBlank()) {
-      schema.addExtension(EXT_CLASS_EXTRA_ANNOTATION, classExtraAnnotation);
+    public static Schema<?> createComposedWrapper(String dataRefName, String classExtraAnnotation) {
+        var schema = new ComposedSchema();
+        schema.setAllOf(List.of(
+                new Schema<>().$ref("#/components/schemas/" + SCHEMA_SERVICE_RESPONSE),
+                new ObjectSchema().addProperty(PROP_DATA, new Schema<>().$ref("#/components/schemas/" + dataRefName))
+        ));
+
+        schema.addExtension(EXT_API_WRAPPER, true);
+        schema.addExtension(EXT_API_WRAPPER_DATATYPE, dataRefName);
+        if (classExtraAnnotation != null && !classExtraAnnotation.isBlank()) {
+            schema.addExtension(EXT_CLASS_EXTRA_ANNOTATION, classExtraAnnotation);
+        }
+        return schema;
     }
-    return schema;
-  }
 }
 ```
 

docs/index.md

@@ -8,10 +8,18 @@ nav_order: 1
 
 Welcome! 👋
 
-This site is generated from the [`spring-boot-openapi-generics-clients`](https://github.com/bsayli/spring-boot-openapi-generics-clients) repository.
+This site is generated from the [
+`spring-boot-openapi-generics-clients`](https://github.com/bsayli/spring-boot-openapi-generics-clients) repository.
 
 ---
 
+---
+layout: default
+title: Adoption Guides
+nav_order: 2
+has_children: true
+---
+
 ## 📘 Adoption Guides
 
 * [Server-Side Adoption](adoption/server-side-adoption.md)