Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Tutorial for OpenAPI generation #189

Merged
merged 4 commits into from
Dec 11, 2021
Merged

Tutorial for OpenAPI generation #189

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5114262
added tutorials for openapi generation
GuentherJulian Dec 6, 2021
08f2d1b
Merge branch 'main' into tutorial_openapi_generation
GuentherJulian Dec 6, 2021
ee399e4
Merge branch 'main' into tutorial_openapi_generation
GuentherJulian Dec 10, 2021
067f9fe
Merge branch 'main' into tutorial_openapi_generation
maybeec Dec 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 154 additions & 0 deletions openapi-generation-servicedocgen/files/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<groupId>org.acme</groupId>
<artifactId>rest-json-quickstart</artifactId>
<version>1.0.0-SNAPSHOT</version>
<properties>
<quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
<quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
<quarkus.platform.version>2.5.1.Final</quarkus.platform.version>
<surefire-plugin.version>3.0.0-M5</surefire-plugin.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>${quarkus.platform.artifact-id}</artifactId>
<version>${quarkus.platform.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy-jackson</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-junit5</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>rest-assured</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>servicedocgen-maven-plugin</artifactId>
<version>1.0.0</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<configuration>
<descriptor>
<info>
<title>Order Service REST API Documentation</title>
<description>This documentation describes the REST API of the order service</description>
<contact>
<email>icsddevonfwsupport.apps2@capgemini.com</email>
<name>devon4j support</name>
<url>https://devonfw.com</url>
</contact>
<license>
<url>https://github.com/devonfw-sample/devon4quarkus-order/blob/master/LICENSE</url>
<name>Apache License 2.0</name>
</license>
</info>
<basePath>/</basePath>
<schemes>
<scheme>http</scheme>
</schemes>
</descriptor>
<classnameRegex>.*Resource.*</classnameRegex>
<templates>
<template>
<templateName>OpenApi.yaml.vm</templateName>
<outputName>OpenApi.yaml</outputName>
</template>
<template>
<templateName>SwaggerUI.html.vm</templateName>
<outputName>SwaggerUI.html</outputName>
</template>
</templates>
</configuration>
</plugin>
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</plugin>
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<executions>
<execution>
<goals>
<goal>build</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>native</id>
<activation>
<property>
<name>native</name>
</property>
</activation>
<properties>
<quarkus.package.type>native</quarkus.package.type>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
77 changes: 77 additions & 0 deletions openapi-generation-servicedocgen/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
= OpenAPI and Swagger UI generation with ServicedocGen plugin
====
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.

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.

For more information about OpenAPI and the ServicedocGen plugin, see the [devon4j documentation](https://github.com/devonfw/devon4j/blob/master/documentation/guide-openapi.asciidoc).

### Prerequisites
* Installed devonfw-ide (or at least Java and Maven installed)

### Learning goals
* You will learn how to generate OpenAPI specifications and Swagger UI from REST services using ServicedocGen maven plugin

====

[step]
--
restoreDevonfwIde(["java", "mvn"])
--

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.
[step]
== Clone quarkus-quickstarts repository
--
cloneRepository("", "https://github.com/quarkusio/quarkus-quickstarts.git")
--

====
Next step is to add the ServicedocGen plugin to the project's pom.xml
[step]
== Add the ServicedocGen maven plugin
--
changeFile("quarkus-quickstarts/rest-json-quickstart/pom.xml", { "file": "files/pom.xml" })
--
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.

Some other parts are necessary. The `classnameRegex` parameter is used to configure which name pattern the REST service classes must match.

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.
====

In this step we will buid the application. This will cause the ServicedocGen plugin to create the configured files.
[step]
== Build the application
--
executeCommand("mvn clean package","mvn clean package", { "dir": "quarkus-quickstarts/rest-json-quickstart" })
--

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.
[step]
== Move generated file to META-INF/resources
--
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" })
--

Now build the application again so that the static files are also included in the resulting jar file.
[step]
== Build the application again
--
executeCommand("mvn clean package","mvn clean package", { "dir": "quarkus-quickstarts/rest-json-quickstart" })
--

====
Now run the application.
[step]
== Run the application
--
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})
--

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

You can access the OpenAPI specification of this REST API at https://[[HOST_SUBDOMAIN]]-8080-[[KATACODA_HOST]].environments.katacoda.com/OpenApi.yaml

The Swagger UI is accessible at https://[[HOST_SUBDOMAIN]]-8080-[[KATACODA_HOST]].environments.katacoda.com/SwaggerUI.html
====
1 change: 1 addition & 0 deletions openapi-generation-smallrye/files/application.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
quarkus.swagger-ui.always-include=true
114 changes: 114 additions & 0 deletions openapi-generation-smallrye/files/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<groupId>org.acme</groupId>
<artifactId>rest-json-quickstart</artifactId>
<version>1.0.0-SNAPSHOT</version>
<properties>
<quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
<quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
<quarkus.platform.version>2.5.1.Final</quarkus.platform.version>
<surefire-plugin.version>3.0.0-M5</surefire-plugin.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>${quarkus.platform.artifact-id}</artifactId>
<version>${quarkus.platform.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy-jackson</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-junit5</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>rest-assured</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</plugin>
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<executions>
<execution>
<goals>
<goal>build</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>native</id>
<activation>
<property>
<name>native</name>
</property>
</activation>
<properties>
<quarkus.package.type>native</quarkus.package.type>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
Loading