Skip to content

Commit 62621f7

Browse files
barissaylibarissayli
committed
docs(adoption): add client-side Maven setup guide with plugins and dependencies
1 parent c45dc49 commit 62621f7

File tree

2 files changed

+204
-0
lines changed

2 files changed

+204
-0
lines changed

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

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Client-Side Build Setup (Maven Plugins & Dependencies)
2+
3+
When adopting the **generics-aware OpenAPI client**, make sure to configure your `pom.xml` with the required plugins and dependencies. These ensure that template overlays are applied correctly and generated sources are compiled into your project.
4+
5+
---
6+
7+
## 1) Core Dependencies
8+
9+
Add these dependencies to your client module:
10+
11+
```xml
12+
<dependencies>
13+
<!-- Spring Boot (provided by host application) -->
14+
<dependency>
15+
<groupId>org.springframework.boot</groupId>
16+
<artifactId>spring-boot-starter-web</artifactId>
17+
<scope>provided</scope>
18+
</dependency>
19+
<dependency>
20+
<groupId>jakarta.validation</groupId>
21+
<artifactId>jakarta.validation-api</artifactId>
22+
<scope>provided</scope>
23+
</dependency>
24+
<dependency>
25+
<groupId>jakarta.annotation</groupId>
26+
<artifactId>jakarta.annotation-api</artifactId>
27+
<scope>provided</scope>
28+
</dependency>
29+
30+
<!-- HTTP client (used by generated code) -->
31+
<dependency>
32+
<groupId>org.apache.httpcomponents.client5</groupId>
33+
<artifactId>httpclient5</artifactId>
34+
<version>5.5</version>
35+
</dependency>
36+
37+
<!-- Test dependencies -->
38+
<dependency>
39+
<groupId>org.springframework.boot</groupId>
40+
<artifactId>spring-boot-starter-test</artifactId>
41+
<scope>test</scope>
42+
</dependency>
43+
<dependency>
44+
<groupId>com.squareup.okhttp3</groupId>
45+
<artifactId>mockwebserver</artifactId>
46+
<version>5.1.0</version>
47+
<scope>test</scope>
48+
</dependency>
49+
</dependencies>
50+
```
51+
52+
---
53+
54+
## 2) Maven Plugins
55+
56+
These plugins **work together** to unpack upstream templates, overlay your custom Mustache files, and generate type-safe client code.
57+
58+
```xml
59+
<build>
60+
<plugins>
61+
<!-- Unpack upstream OpenAPI templates -->
62+
<plugin>
63+
<groupId>org.apache.maven.plugins</groupId>
64+
<artifactId>maven-dependency-plugin</artifactId>
65+
<executions>
66+
<execution>
67+
<id>unpack-openapi-upstream-templates</id>
68+
<phase>generate-sources</phase>
69+
<goals><goal>unpack</goal></goals>
70+
<configuration>
71+
<artifactItems>
72+
<artifactItem>
73+
<groupId>org.openapitools</groupId>
74+
<artifactId>openapi-generator</artifactId>
75+
<version>${openapi.generator.version}</version>
76+
<type>jar</type>
77+
<includes>templates/Java/**</includes>
78+
<outputDirectory>${openapi.templates.upstream}</outputDirectory>
79+
</artifactItem>
80+
</artifactItems>
81+
</configuration>
82+
</execution>
83+
</executions>
84+
</plugin>
85+
86+
<!-- Overlay local Mustache templates on top of upstream -->
87+
<plugin>
88+
<groupId>org.apache.maven.plugins</groupId>
89+
<artifactId>maven-resources-plugin</artifactId>
90+
<executions>
91+
<execution>
92+
<id>copy-upstream-to-effective</id>
93+
<phase>generate-sources</phase>
94+
<goals><goal>copy-resources</goal></goals>
95+
<configuration>
96+
<outputDirectory>${openapi.templates.effective}</outputDirectory>
97+
<resources>
98+
<resource>
99+
<directory>${openapi.templates.upstream}/templates</directory>
100+
<includes><include>Java/**</include></includes>
101+
</resource>
102+
</resources>
103+
</configuration>
104+
</execution>
105+
<execution>
106+
<id>overlay-local-templates</id>
107+
<phase>generate-sources</phase>
108+
<goals><goal>copy-resources</goal></goals>
109+
<configuration>
110+
<outputDirectory>${openapi.templates.effective}/Java</outputDirectory>
111+
<overwrite>true</overwrite>
112+
<resources>
113+
<resource>
114+
<directory>src/main/resources/openapi-templates</directory>
115+
<includes><include>**/*.mustache</include></includes>
116+
</resource>
117+
</resources>
118+
</configuration>
119+
</execution>
120+
</executions>
121+
</plugin>
122+
123+
<!-- Generate OpenAPI client code -->
124+
<plugin>
125+
<groupId>org.openapitools</groupId>
126+
<artifactId>openapi-generator-maven-plugin</artifactId>
127+
<version>${openapi.generator.version}</version>
128+
<executions>
129+
<execution>
130+
<id>generate-client</id>
131+
<phase>generate-sources</phase>
132+
<goals><goal>generate</goal></goals>
133+
<configuration>
134+
<inputSpec>${project.basedir}/src/main/resources/your-api-docs.yaml</inputSpec>
135+
<generatorName>java</generatorName>
136+
<library>restclient</library>
137+
<output>${project.build.directory}/generated-sources/openapi</output>
138+
139+
<apiPackage>your.base.openapi.client.generated.api</apiPackage>
140+
<modelPackage>your.base.openapi.client.generated.dto</modelPackage>
141+
<invokerPackage>your.base.openapi.client.generated.invoker</invokerPackage>
142+
143+
<templateDirectory>${openapi.templates.effective}/Java</templateDirectory>
144+
<generateSupportingFiles>true</generateSupportingFiles>
145+
<generateApiTests>false</generateApiTests>
146+
<generateModelTests>false</generateModelTests>
147+
148+
<configOptions>
149+
<useSpringBoot3>true</useSpringBoot3>
150+
<useJakartaEe>true</useJakartaEe>
151+
<serializationLibrary>jackson</serializationLibrary>
152+
<dateLibrary>java8</dateLibrary>
153+
<useBeanValidation>true</useBeanValidation>
154+
<openApiNullable>false</openApiNullable>
155+
<sourceFolder>src/gen/java</sourceFolder>
156+
</configOptions>
157+
158+
<additionalProperties>
159+
<additionalProperty>commonPackage=your.base.openapi.client.common</additionalProperty>
160+
</additionalProperties>
161+
</configuration>
162+
</execution>
163+
</executions>
164+
</plugin>
165+
166+
<!-- Add generated sources to compilation -->
167+
<plugin>
168+
<groupId>org.codehaus.mojo</groupId>
169+
<artifactId>build-helper-maven-plugin</artifactId>
170+
<executions>
171+
<execution>
172+
<id>add-generated-sources</id>
173+
<phase>generate-sources</phase>
174+
<goals><goal>add-source</goal></goals>
175+
<configuration>
176+
<sources>
177+
<source>${project.build.directory}/generated-sources/openapi/src/gen/java</source>
178+
</sources>
179+
</configuration>
180+
</execution>
181+
</executions>
182+
</plugin>
183+
</plugins>
184+
</build>
185+
```
186+
187+
---
188+
189+
## 3) Why These Plugins Matter
190+
191+
* **maven-dependency-plugin** → unpacks stock OpenAPI templates.
192+
* **maven-resources-plugin** → overlays your custom Mustache files.
193+
* **openapi-generator-maven-plugin** → generates the client code.
194+
* **build-helper-maven-plugin** → makes sure generated code is compiled.
195+
196+
Together, these steps ensure **your generics-aware wrappers** are generated correctly and seamlessly integrated into the build.

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,4 +200,12 @@ your-service-client/
200200

201201
---
202202

203+
## 11) Maven Setup
204+
205+
See [Client-Side Adoption (POM Setup)](client-side-adoption-pom.md) for the full `pom.xml` configuration, including
206+
required plugins (`maven-dependency-plugin`, `maven-resources-plugin`, `openapi-generator-maven-plugin`, etc.)
207+
and dependency declarations.
208+
209+
---
210+
203211
✅ With this setup, your client project generates **type-safe wrappers** that align with `ServiceResponse<T>` from the server side, without any boilerplate duplication.

0 commit comments

Comments
 (0)