Skip to content

Commit

Permalink
Openapi restdoc generation v2 (#1442)
Browse files Browse the repository at this point in the history 
* OpenApi restdoc generation v2

Signed-off-by: Denislav Prinov <[email protected]>

* Attach json and yaml artifacts only if -DskipTests is not provided

Signed-off-by: Denislav Prinov <[email protected]>

* Add missing header

Signed-off-by: Denislav Prinov <[email protected]>

* Add license header

Signed-off-by: Denislav Prinov <[email protected]>

---------

Signed-off-by: Denislav Prinov <[email protected]>
  • Loading branch information
@denislavprinov
denislavprinov authored Oct 2, 2023
1 parent 60f1469 commit a420495
Show file tree
Hide file tree
Showing 6 changed files with 222 additions and 128 deletions.
7 changes: 3 additions & 4 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,9 @@ theme. Compiling the documentation is not included within the regular Maven buil

## Prerequisites
1. **Install Hugo**: see [installing Hugo](https://gohugo.io/getting-started/installing/) documentation on how to install Hugo.
2. **Install JQ**: see [installing jq](https://jqlang.github.io/jq/download/) documentation on how to install jq.
3. **Install NODE.js and npm** see [installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) documentation on how to install Node.js and npm
4. **Install Redocly CLI** see [installing Redocly CLI](https://redocly.com/docs/cli/installation/) documentation on how to install Redocly CLI
5. **Install hawkBit**: run `mvn install` in the parent directory to generate the latest REST docs for hawkBit.
2. **Install NODE.js and npm** see [installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) documentation on how to install Node.js and npm
3. **Install Redocly CLI** see [installing Redocly CLI](https://redocly.com/docs/cli/installation/) documentation on how to install Redocly CLI
4. **Install hawkBit**: run `mvn install` in the parent directory to generate the latest REST docs for hawkBit.


## Build and Serve documentation
Expand Down
4 changes: 2 additions & 2 deletions docs/build-htmls.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ else
fi

# Execute the npx command
npx @redocly/cli build-docs ${CURRENT_DIR}/content/rest-api/mgmt.json -o ${CURRENT_DIR}/content/rest-api/mgmt.html
npx @redocly/cli build-docs ${CURRENT_DIR}/content/rest-api/mgmt.yaml -o ${CURRENT_DIR}/content/rest-api/mgmt.html

if [ $? != 0 ]; then
echo "[ERROR] Failed to execute the Redoc CLI command form MGMT API."
Expand All @@ -34,7 +34,7 @@ else
fi

# Execute the npx command
npx @redocly/cli build-docs ${CURRENT_DIR}/content/rest-api/ddi.json -o ${CURRENT_DIR}/content/rest-api/ddi.html
npx @redocly/cli build-docs ${CURRENT_DIR}/content/rest-api/ddi.yaml -o ${CURRENT_DIR}/content/rest-api/ddi.html

if [ $? != 0 ]; then
echo "[ERROR] Failed to execute the Redoc CLI command form DDI API."
Expand Down
31 changes: 13 additions & 18 deletions docs/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,11 +72,21 @@
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-update-server</artifactId>
<version>${project.version}</version>
<classifier>openapi</classifier>
<type>json</type>
<classifier>mgmt-openapi</classifier>
<type>yaml</type>
<overWrite>true</overWrite>
<outputDirectory>${basedir}/content/rest-api</outputDirectory>
<destFileName>openapi.json</destFileName>
<destFileName>mgmt.yaml</destFileName>
</artifactItem>
<artifactItem>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-update-server</artifactId>
<version>${project.version}</version>
<classifier>ddi-openapi</classifier>
<type>yaml</type>
<overWrite>true</overWrite>
<outputDirectory>${basedir}/content/rest-api</outputDirectory>
<destFileName>ddi.yaml</destFileName>
</artifactItem>
</artifactItems>
</configuration>
Expand All @@ -88,21 +98,6 @@
<artifactId>exec-maven-plugin</artifactId>
<version>${exec-maven-plugin.version}</version>
<executions>
<execution>
<id>split-docs</id>
<goals>
<goal>exec</goal>
</goals>
<phase>install</phase>
<configuration>
<executable>${shell}</executable>
<workingDirectory>${project.basedir}</workingDirectory>
<arguments>
<argument>${shell.option}</argument>
<argument>split-doc.${batch.ext}</argument>
</arguments>
</configuration>
</execution>
<execution>
<id>build-htmls</id>
<goals>
Expand Down
52 changes: 0 additions & 52 deletions docs/split-doc.sh
View file

This file was deleted.

102 changes: 50 additions & 52 deletions hawkbit-runtime/hawkbit-update-server/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,65 +32,63 @@
</plugins>
</build>
</profile>
<profile>
<id>attach-artifacts-profile</id>
<!-- This profile activates when -DskipTests is not provided -->
<activation>
<property>
<name>!skipTests</name>
</property>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>attach-artifacts</id>
<phase>package</phase>
<goals>
<goal>attach-artifact</goal>
</goals>
<configuration>
<artifacts>
<artifact>
<file>${project.build.directory}/rest-api/mgmt-openapi.json</file>
<type>json</type>
<classifier>mgmt-openapi</classifier>
</artifact>
<artifact>
<file>${project.build.directory}/rest-api/mgmt-openapi.yaml</file>
<type>yaml</type>
<classifier>mgmt-openapi</classifier>
</artifact>
<artifact>
<file>${project.build.directory}/rest-api/ddi-openapi.json</file>
<type>json</type>
<classifier>ddi-openapi</classifier>
</artifact>
<artifact>
<file>${project.build.directory}/rest-api/ddi-openapi.yaml</file>
<type>yaml</type>
<classifier>ddi-openapi</classifier>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<build>
<plugins>
<!-- Generating the rest doc during integration tests -->
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>1.4</version>
<executions>
<!-- Execution for JSON -->
<execution>
<id>generate-json</id>
<phase>integration-test</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<outputFileName>openapi.json</outputFileName>
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
<attachArtifact>true</attachArtifact>
</configuration>
</execution>
<!-- Execution for YAML -->
<execution>
<id>generate-yaml</id>
<phase>integration-test</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<outputFileName>openapi.yaml</outputFileName>
<apiDocsUrl>http://localhost:8080/v3/api-docs.yaml</apiDocsUrl>
<attachArtifact>true</attachArtifact>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
<mainClass>org.eclipse.hawkbit.app.Start</mainClass>
</configuration>
<executions>
<execution>
<phase>pre-integration-test</phase>
<id>pre-api-docs-generation</id>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-api-docs-generation</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
<execution>
<goals>
<goal>repackage</goal>
Expand Down
Loading

0 comments on commit a420495

Please sign in to comment.