Skip to content

Commit 46d4c3a

Browse files
haunerhauner
committed
added docs
1 parent 6d2834f commit 46d4c3a

4 files changed

Lines changed: 280 additions & 0 deletions

File tree

‎docs/antora.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
name: gradle
2+
title: oap-maven
3+
version: master
4+
nav:
5+
- modules/ROOT/nav.adoc

‎docs/modules/ROOT/images/openapi-processor-maven@1280x200.png‎

12 KB
Loading

‎docs/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* xref:index.adoc[Documentation]

‎docs/modules/ROOT/pages/index.adoc‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
:author: Martin Hauner
2+
:page-title: openapi-processor-maven
3+
:page-aliases: current@gradle:ROOT:index.adoc, latest@gradle:ROOT:index.adoc
4+
:badge-license: https://img.shields.io/badge/License-Apache%202.0-blue.svg?labelColor=313A42
5+
:badge-ci: https://github.com/openapi-processor/openapi-processor-maven/workflows/ci/badge.svg
6+
:oapj-ci: https://github.com/openapi-processor/openapi-processor-maven/actions?query=workflow%3Aci
7+
:oapj-license: https://github.com/openapi-processor/openapi-processor-maven/blob/master/LICENSE
8+
:oap-api: https://github.com/openapi-processor/openapi-processor-api
9+
10+
//
11+
// content
12+
//
13+
image:openapi-processor-maven$$@$$1280x200.png[openapi-processor-maven]
14+
15+
// badges
16+
//link:{oapj-ci}[image:{badge-ci}[]]
17+
link:{oapj-license}[image:{badge-license}[]]
18+
19+
20+
a maven plugin based on the link:{oap-api}[openapi-processor-api] to handle any openapi-processor without an explicit dependency on the processor.
21+
22+
== compatibility
23+
24+
[cols="3*",options="header"]
25+
|===
26+
| plugin version
27+
| minimum maven version
28+
| description
29+
30+
| 1.0.0.M1 (not yet released)
31+
| 3.6 (?)
32+
a| supports processors with new `io.openapiprocessor` and old `com.github.hauner.openapi` group id
33+
|===
34+
35+
36+
== plugin configuration
37+
38+
The first step of the configuration is to add the plugin, and the processor(s) to an existing project `pom.xml` into the `<plugins/>` block.
39+
40+
[source,xml]
41+
----
42+
<?xml version="1.0" encoding="UTF-8"?>
43+
<project xmlns="http://maven.apache.org/POM/4.0.0" ... >
44+
<build>
45+
<plugins>
46+
<plugin>
47+
<groupId>io.openapiprocessor</groupId>
48+
<artifactId>openapi-processor-maven-plugin</artifactId>
49+
<version>1.0.0.M1-SNAPSHOT</version>
50+
51+
<!-- ... next step ... -->
52+
</plugin>
53+
</plugins>
54+
</build>
55+
</project>
56+
----
57+
58+
The processors are dependencies of the plugin, and they are expected in the `<plugin/>` block added in the first step.
59+
60+
[source,xml]
61+
----
62+
<plugin>
63+
<dependencies>
64+
<dependency>
65+
<groupId>io.openapiprocessor</groupId>
66+
<artifactId>openapi-processor-spring</artifactId>
67+
<version>1.0.0.M15</version>
68+
</dependency>
69+
<dependency>
70+
<groupId>com.github.hauner.openapi</groupId>
71+
<artifactId>openapi-processor-json</artifactId>
72+
<version>1.0.0.M4</version>
73+
</dependency>
74+
</dependencies>
75+
76+
<!-- ... next step ... -->
77+
</plugin>
78+
----
79+
80+
Then it should know where the processors will find the input OpenAPI yaml files using the `<apiPath/>` element:
81+
82+
[source,xml]
83+
----
84+
<plugin>
85+
<configuration>
86+
<apiPath>${project.basedir}/src/api/openapi.yaml</apiPath>
87+
</configuration>
88+
89+
<!-- ... next step ... -->
90+
</plugin>
91+
----
92+
93+
* `*<apiPath/>*`, defines the path to the openapi yaml file. This is usually the same for all processors and adding it directly into the plugin `<configuration/>` block sets it for all processors.
94+
95+
Next step is to configure the goals for processing. The plugin has only a single goal `process` that can run any processor. It is configured by an `<execution/>` element to run a specific processor.
96+
97+
If maven should run multiple processors, multiple `<execution/>` s are needed.
98+
99+
Here is an example to run `openapi-processor-spring` that explains the configuration details:
100+
101+
[source,xml]
102+
----
103+
<plugin>
104+
<executions>
105+
<execution>
106+
<id>spring</id> <!-- 1 -->
107+
<phase>generate-sources</phase> <!-- 2 -->
108+
109+
<configuration>
110+
<id>spring</id> <!-- 3 -->
111+
112+
<!-- 4
113+
<apiPath>${project.basedir}/src/api/openapi.yaml</apiPath>
114+
-->
115+
116+
<options> <!-- 5 -->
117+
<values>
118+
<targetDir>${project.basedir}/target/generated-sources/openapi</targetDir> <!-- 6 -->
119+
<mapping>${project.basedir}/src/api/mapping.yaml</mapping> <!-- 7 -->
120+
<parser>OPENAPI4J</parser>
121+
<showWarnings>true</showWarnings>
122+
</values>
123+
124+
<nested>
125+
<name>foo</name>
126+
<values>
127+
<bar>foo-bar</foobar>
128+
</values>
129+
</nested>
130+
131+
</options>
132+
</configuration>
133+
134+
<goals>
135+
<goal>process</goal> <!-- 8 -->
136+
</goals>
137+
</execution>
138+
</executions>
139+
</plugin>
140+
----
141+
142+
<1> `*<id/>*`: **execution id** of the goal (choose your id). It is necessary to configure multiple executions.
143+
144+
<2> `*<phase/>*` **phase** (mandatory): openapi-processor-spring generates java code, so the `<phase/>` should be `generate-source`. This tells maven to run the goal before compiling anything.
145+
146+
<3> `*<id/>*` **processor id** (mandatory): this configures the openapi-processor the goal should run. The processor id must match exactly with the name of the processor. The convention is, that the last part of the processors artifact name is the processor id.
147+
+
148+
If the artifact of a processor is called `openapi-processor-x`, the last part `x` is the id of the processor. For example for `openapi-processor-spring` the id is `spring`, for `openapi-processor-json` the id is `json`.
149+
150+
<4> `*<apiPath/>*` (optional): the path to the open api yaml file. If set inside an `<execution>` `<configuration/>` it overrides the parent `apiPath` set in the `<plugin>` `<configuration/>`.
151+
152+
<5> `*<options/>*` (mandatory): **processor specific options**, the configuration of a single processor can have any number of additional parameters defined by the processor (all options will be passed as a map to the processor with the option name as the key). The nested `*<values/>*` element defines that map.
153+
+
154+
To allow any level of nesting it is possible to create `*<nested/>*` option maps, i.e. `*<nested/>*` can contain another `*<nested/>*` element and so on. In the configuration above the plugin would pass the following map to the processor:
155+
+
156+
[source,json,title=json notation]
157+
----
158+
{
159+
"targetDir": "<basedir path>/target/generated-sources/openapi",
160+
"mapping": "<basedir path>/src/api/mapping.yaml",
161+
"parser": "OPENAPI4J",
162+
"showWarnings":true,
163+
"foo": {
164+
"bar": "foo-bar"
165+
}
166+
}
167+
----
168+
169+
<6> `*<targetDir/>*` **target directory** (mandatory): the directory the processor should use for its output. By convention a processor should use this key to as the output directory.
170+
171+
<7> the rest of the options are processor specific. See xref:spring::index.doc[openapi-processor-spring].
172+
173+
<8> `*<goal/>*` **goal** (mandatory): this is the goal maven should run. Since the plugin does only have a single goal the value is always `process`.
174+
175+
176+
To run a second processor add another `<execution>` element. Here is an example that configures xref:spring:ROOT:index.adoc[openapi-processor-spring] and xref:json:ROOT:index.adoc[openapi-processor-json]:
177+
178+
179+
[source,xml]
180+
----
181+
<plugin>
182+
<executions>
183+
<execution>
184+
<id>spring</id>
185+
<phase>generate-sources</phase>
186+
187+
<configuration>
188+
<id>spring</id>
189+
<!-- ... -->
190+
</configuration>
191+
</execution>
192+
193+
<execution>
194+
<id>json</id>
195+
<phase>generate-resources</phase> <!-- 1 -->
196+
197+
<configuration>
198+
<id>json</id>
199+
<!-- ... -->
200+
</configuration>
201+
</execution>
202+
</executions>
203+
</plugin>
204+
----
205+
206+
<1> uses `generate-resources` phase for the json output, to consider it as a resource.
207+
208+
209+
== using the processor output
210+
211+
So far the plugin processes the given openapi yaml and writes the output to the given target directory but maven ignores the output.
212+
213+
It is necessary to tell maven to use the generated files. In case of generated java source files maven should compile them. The *build-helper-maven-plugin* is used to for this:
214+
215+
[source,xml]
216+
----
217+
<?xml version="1.0" encoding="UTF-8"?>
218+
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
219+
<build>
220+
<plugins>
221+
<plugin>
222+
<groupId>org.codehaus.mojo</groupId>
223+
<artifactId>build-helper-maven-plugin</artifactId>
224+
<executions>
225+
<execution>
226+
<id>oap-sources</id>
227+
<phase>generate-sources</phase>
228+
<goals>
229+
<goal>add-source</goal>
230+
</goals>
231+
<configuration>
232+
<sources>
233+
<source>${project.build.directory}/generated-sources/openapi</source>
234+
</sources>
235+
</configuration>
236+
</execution>
237+
238+
239+
</executions>
240+
</plugin>
241+
242+
</plugins>
243+
</build>
244+
</project>
245+
----
246+
247+
This tells the *build-helper-maven-plugin* to add the processors `targetDir` as an additional source folder to the project.
248+
249+
Maven will now include the generated files when it compiles the project.
250+
251+
If the output of the processor (e.g. generated by openapi-processor-json) should be used as resource the *build-helper-maven-plugin* has a goal for this too. Just add another `<excecution/>` using the `add-resource` goal:
252+
253+
[source,xml]
254+
----
255+
<execution>
256+
<id>oap-resources</id>
257+
<phase>generate-resources</phase>
258+
<goals>
259+
<goal>add-resource</goal>
260+
</goals>
261+
<configuration>
262+
<resources>
263+
<resource>
264+
<directory>${project.build.directory}/generated-resources/json</directory>
265+
</resource>
266+
</resources>
267+
</configuration>
268+
</execution>
269+
----
270+
271+
272+
== Samples
273+
274+
See the maven sample in the xref:sample::index.adoc[samples] for a working spring boot example.

0 commit comments

Comments
 (0)