Skip to content

Commit 58d1306

Browse files
maybeecmaybeec
authored
Merge pull request #189 from GuentherJulian/tutorial_openapi_generation
Tutorial for OpenAPI generation
2 parents b94f029 + 067f9fe commit 58d1306

5 files changed

Lines changed: 399 additions & 0 deletions

File tree

‎openapi-generation-servicedocgen/files/pom.xml‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
<?xml version="1.0"?>
2+
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
3+
xmlns="http://maven.apache.org/POM/4.0.0"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
5+
<modelVersion>4.0.0</modelVersion>
6+
<groupId>org.acme</groupId>
7+
<artifactId>rest-json-quickstart</artifactId>
8+
<version>1.0.0-SNAPSHOT</version>
9+
<properties>
10+
<quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
11+
<quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
12+
<quarkus.platform.version>2.5.1.Final</quarkus.platform.version>
13+
<surefire-plugin.version>3.0.0-M5</surefire-plugin.version>
14+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
15+
<maven.compiler.source>11</maven.compiler.source>
16+
<maven.compiler.target>11</maven.compiler.target>
17+
</properties>
18+
19+
<dependencyManagement>
20+
<dependencies>
21+
<dependency>
22+
<groupId>${quarkus.platform.group-id}</groupId>
23+
<artifactId>${quarkus.platform.artifact-id}</artifactId>
24+
<version>${quarkus.platform.version}</version>
25+
<type>pom</type>
26+
<scope>import</scope>
27+
</dependency>
28+
</dependencies>
29+
</dependencyManagement>
30+
31+
<dependencies>
32+
<dependency>
33+
<groupId>io.quarkus</groupId>
34+
<artifactId>quarkus-resteasy-jackson</artifactId>
35+
</dependency>
36+
<dependency>
37+
<groupId>io.quarkus</groupId>
38+
<artifactId>quarkus-junit5</artifactId>
39+
<scope>test</scope>
40+
</dependency>
41+
<dependency>
42+
<groupId>io.rest-assured</groupId>
43+
<artifactId>rest-assured</artifactId>
44+
<scope>test</scope>
45+
</dependency>
46+
</dependencies>
47+
<build>
48+
<plugins>
49+
<plugin>
50+
<groupId>org.codehaus.mojo</groupId>
51+
<artifactId>servicedocgen-maven-plugin</artifactId>
52+
<version>1.0.0</version>
53+
<executions>
54+
<execution>
55+
<goals>
56+
<goal>generate</goal>
57+
</goals>
58+
</execution>
59+
</executions>
60+
<configuration>
61+
<descriptor>
62+
<info>
63+
<title>Order Service REST API Documentation</title>
64+
<description>This documentation describes the REST API of the order service</description>
65+
<contact>
66+
<email>icsddevonfwsupport.apps2@capgemini.com</email>
67+
<name>devon4j support</name>
68+
<url>https://devonfw.com</url>
69+
</contact>
70+
<license>
71+
<url>https://github.com/devonfw-sample/devon4quarkus-order/blob/master/LICENSE</url>
72+
<name>Apache License 2.0</name>
73+
</license>
74+
</info>
75+
<basePath>/</basePath>
76+
<schemes>
77+
<scheme>http</scheme>
78+
</schemes>
79+
</descriptor>
80+
<classnameRegex>.*Resource.*</classnameRegex>
81+
<templates>
82+
<template>
83+
<templateName>OpenApi.yaml.vm</templateName>
84+
<outputName>OpenApi.yaml</outputName>
85+
</template>
86+
<template>
87+
<templateName>SwaggerUI.html.vm</templateName>
88+
<outputName>SwaggerUI.html</outputName>
89+
</template>
90+
</templates>
91+
</configuration>
92+
</plugin>
93+
<plugin>
94+
<artifactId>maven-surefire-plugin</artifactId>
95+
<version>${surefire-plugin.version}</version>
96+
<configuration>
97+
<systemPropertyVariables>
98+
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
99+
<maven.home>${maven.home}</maven.home>
100+
</systemPropertyVariables>
101+
</configuration>
102+
</plugin>
103+
<plugin>
104+
<groupId>${quarkus.platform.group-id}</groupId>
105+
<artifactId>quarkus-maven-plugin</artifactId>
106+
<version>${quarkus.platform.version}</version>
107+
<executions>
108+
<execution>
109+
<goals>
110+
<goal>build</goal>
111+
</goals>
112+
</execution>
113+
</executions>
114+
</plugin>
115+
</plugins>
116+
</build>
117+
<profiles>
118+
<profile>
119+
<id>native</id>
120+
<activation>
121+
<property>
122+
<name>native</name>
123+
</property>
124+
</activation>
125+
<properties>
126+
<quarkus.package.type>native</quarkus.package.type>
127+
</properties>
128+
<build>
129+
<plugins>
130+
<plugin>
131+
<groupId>org.apache.maven.plugins</groupId>
132+
<artifactId>maven-failsafe-plugin</artifactId>
133+
<version>${surefire-plugin.version}</version>
134+
<executions>
135+
<execution>
136+
<goals>
137+
<goal>integration-test</goal>
138+
<goal>verify</goal>
139+
</goals>
140+
<configuration>
141+
<systemPropertyVariables>
142+
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
143+
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
144+
<maven.home>${maven.home}</maven.home>
145+
</systemPropertyVariables>
146+
</configuration>
147+
</execution>
148+
</executions>
149+
</plugin>
150+
</plugins>
151+
</build>
152+
</profile>
153+
</profiles>
154+
</project>

‎openapi-generation-servicedocgen/index.asciidoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
= OpenAPI and Swagger UI generation with ServicedocGen plugin
2+
====
3+
This tutorial will teach you how to use the [ServicedocGen maven plugin](http://www.mojohaus.org/servicedocgen-maven-plugin/) to generate the OpenAPI specification and Swagger UI from your REST APIs.
4+
5+
The plugin analysis the REST APIs and the associated JavaDoc and then generates the OpenAPI specification as a static file. It is also able to create an HTML file that represents the Swagger UI and can be served by Quarkus to provide the Swagger UI in the browser.
6+
7+
For more information about OpenAPI and the ServicedocGen plugin, see the [devon4j documentation](https://github.com/devonfw/devon4j/blob/master/documentation/guide-openapi.asciidoc).
8+
9+
### Prerequisites
10+
* Installed devonfw-ide (or at least Java and Maven installed)
11+
12+
### Learning goals
13+
* You will learn how to generate OpenAPI specifications and Swagger UI from REST services using ServicedocGen maven plugin
14+
15+
====
16+
17+
[step]
18+
--
19+
restoreDevonfwIde(["java", "mvn"])
20+
--
21+
22+
First, clone the `quarkus-quickstarts` repository from GitHub. It contains several sample applications for many extensions to Quarkus. For this tutorial, we will use an application with a simple REST service contained in the `rest-json-quickstart` subfolder.
23+
[step]
24+
== Clone quarkus-quickstarts repository
25+
--
26+
cloneRepository("", "https://github.com/quarkusio/quarkus-quickstarts.git")
27+
--
28+
29+
====
30+
Next step is to add the ServicedocGen plugin to the project's pom.xml
31+
[step]
32+
== Add the ServicedocGen maven plugin
33+
--
34+
changeFile("quarkus-quickstarts/rest-json-quickstart/pom.xml", { "file": "files/pom.xml" })
35+
--
36+
Take a look at the `configuration` section of the plugin. In this section you can configure the behavior of the plugin. Not all options are necessary, such as the `info` section. This one is only used to add additional information to the OpenAPI file.
37+
38+
Some other parts are necessary. The `classnameRegex` parameter is used to configure which name pattern the REST service classes must match.
39+
40+
The `templates` section is used to configure what is created by the plugin. In this case, the OpenAPI specification is created in yaml format and the Swagger UI file is also created.
41+
====
42+
43+
In this step we will buid the application. This will cause the ServicedocGen plugin to create the configured files.
44+
[step]
45+
== Build the application
46+
--
47+
executeCommand("mvn clean package","mvn clean package", { "dir": "quarkus-quickstarts/rest-json-quickstart" })
48+
--
49+
50+
The files are created in the `target/site/servicedoc` folder. To serve them automatically when running the application, move the files to the `src/main/resources/META-INF/resources/` folder. Static files located in this folder are automatically served by Quarkus.
51+
[step]
52+
== Move generated file to META-INF/resources
53+
--
54+
executeCommand("copy target\\site\\servicedoc\\*.* src\\main\\resources\\META-INF\\resources","mv target/site/servicedoc/* src/main/resources/META-INF/resources/", { "dir": "quarkus-quickstarts/rest-json-quickstart" })
55+
--
56+
57+
Now build the application again so that the static files are also included in the resulting jar file.
58+
[step]
59+
== Build the application again
60+
--
61+
executeCommand("mvn clean package","mvn clean package", { "dir": "quarkus-quickstarts/rest-json-quickstart" })
62+
--
63+
64+
====
65+
Now run the application.
66+
[step]
67+
== Run the application
68+
--
69+
executeCommand("java -jar quarkus-run.jar","java -jar quarkus-run.jar", { "dir": "quarkus-quickstarts/rest-json-quickstart/target/quarkus-app", "asynchronous": true }, {"port":8080 , "startupTime": 120, "path": "fruits", "interval": 2})
70+
--
71+
72+
After executing `java -jar quarkus-run.jar` you can access the REST service by opening the following URL: https://[[HOST_SUBDOMAIN]]-8080-[[KATACODA_HOST]].environments.katacoda.com/fruits
73+
74+
You can access the OpenAPI specification of this REST API at https://[[HOST_SUBDOMAIN]]-8080-[[KATACODA_HOST]].environments.katacoda.com/OpenApi.yaml
75+
76+
The Swagger UI is accessible at https://[[HOST_SUBDOMAIN]]-8080-[[KATACODA_HOST]].environments.katacoda.com/SwaggerUI.html
77+
====

‎openapi-generation-smallrye/files/application.properties‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
quarkus.swagger-ui.always-include=true

‎openapi-generation-smallrye/files/pom.xml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
<?xml version="1.0"?>
2+
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
3+
xmlns="http://maven.apache.org/POM/4.0.0"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
5+
<modelVersion>4.0.0</modelVersion>
6+
<groupId>org.acme</groupId>
7+
<artifactId>rest-json-quickstart</artifactId>
8+
<version>1.0.0-SNAPSHOT</version>
9+
<properties>
10+
<quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
11+
<quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
12+
<quarkus.platform.version>2.5.1.Final</quarkus.platform.version>
13+
<surefire-plugin.version>3.0.0-M5</surefire-plugin.version>
14+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
15+
<maven.compiler.source>11</maven.compiler.source>
16+
<maven.compiler.target>11</maven.compiler.target>
17+
</properties>
18+
19+
<dependencyManagement>
20+
<dependencies>
21+
<dependency>
22+
<groupId>${quarkus.platform.group-id}</groupId>
23+
<artifactId>${quarkus.platform.artifact-id}</artifactId>
24+
<version>${quarkus.platform.version}</version>
25+
<type>pom</type>
26+
<scope>import</scope>
27+
</dependency>
28+
</dependencies>
29+
</dependencyManagement>
30+
31+
<dependencies>
32+
<dependency>
33+
<groupId>io.quarkus</groupId>
34+
<artifactId>quarkus-resteasy-jackson</artifactId>
35+
</dependency>
36+
<dependency>
37+
<groupId>io.quarkus</groupId>
38+
<artifactId>quarkus-smallrye-openapi</artifactId>
39+
</dependency>
40+
<dependency>
41+
<groupId>io.quarkus</groupId>
42+
<artifactId>quarkus-junit5</artifactId>
43+
<scope>test</scope>
44+
</dependency>
45+
<dependency>
46+
<groupId>io.rest-assured</groupId>
47+
<artifactId>rest-assured</artifactId>
48+
<scope>test</scope>
49+
</dependency>
50+
</dependencies>
51+
<build>
52+
<plugins>
53+
<plugin>
54+
<artifactId>maven-surefire-plugin</artifactId>
55+
<version>${surefire-plugin.version}</version>
56+
<configuration>
57+
<systemPropertyVariables>
58+
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
59+
<maven.home>${maven.home}</maven.home>
60+
</systemPropertyVariables>
61+
</configuration>
62+
</plugin>
63+
<plugin>
64+
<groupId>${quarkus.platform.group-id}</groupId>
65+
<artifactId>quarkus-maven-plugin</artifactId>
66+
<version>${quarkus.platform.version}</version>
67+
<executions>
68+
<execution>
69+
<goals>
70+
<goal>build</goal>
71+
</goals>
72+
</execution>
73+
</executions>
74+
</plugin>
75+
</plugins>
76+
</build>
77+
<profiles>
78+
<profile>
79+
<id>native</id>
80+
<activation>
81+
<property>
82+
<name>native</name>
83+
</property>
84+
</activation>
85+
<properties>
86+
<quarkus.package.type>native</quarkus.package.type>
87+
</properties>
88+
<build>
89+
<plugins>
90+
<plugin>
91+
<groupId>org.apache.maven.plugins</groupId>
92+
<artifactId>maven-failsafe-plugin</artifactId>
93+
<version>${surefire-plugin.version}</version>
94+
<executions>
95+
<execution>
96+
<goals>
97+
<goal>integration-test</goal>
98+
<goal>verify</goal>
99+
</goals>
100+
<configuration>
101+
<systemPropertyVariables>
102+
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
103+
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
104+
<maven.home>${maven.home}</maven.home>
105+
</systemPropertyVariables>
106+
</configuration>
107+
</execution>
108+
</executions>
109+
</plugin>
110+
</plugins>
111+
</build>
112+
</profile>
113+
</profiles>
114+
</project>

0 commit comments

Comments
 (0)