lingwei.kong/hawkbit
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

HTTP documentation generation from OpenApi documentation (#1438)

Browse Source 
* Generating rest doc from swagger json

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

* refactoring and adding doc

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

* refactoring

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

* Don't directly inject files in the executable jar since it brakes it

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

* using the attachArtifact configuration to generate secondary artifact

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

* Splitting the json documentation into mgmt and ddi. And some refactoring

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

* refactoring

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

* Split mgmt and DDI components from the json

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>

---------

Signed-off-by: Denislav Prinov <denislav.prinov@bosch.com>
This commit is contained in:
Denislav Prinov
2023-09-27 11:44:30 +03:00
committed by GitHub
parent 7d76a5a97e
commit 3978454900
23 changed files with 308 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/content/apis/mgmt/_index.md → .gitmodules vendored
View File

5
docs/README.md
View File

@@ -4,7 +4,10 @@ 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 hawkBit**: run `mvn install` in the parent directory to generate the latest REST docs for hawkBit.
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.
## Build and Serve documentation

44
docs/build-htmls.sh Normal file
View File

@@ -0,0 +1,44 @@
#
# Copyright (c) 2018 Bosch Software Innovations GmbH and others
#
# This program and the accompanying materials are made
# available under the terms of the Eclipse Public License 2.0
# which is available at https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
#
#!/bin/bash
CURRENT_DIR=$(pwd)
# Checking for Redoc CLI and npm
redoc-cli --version > /dev/null 2>&1
if [ $? != 0 ]; then
echo "[ERROR] Redoc CLI is not installed! Please make suer to install it before trying again."
exit 1
else
echo "[INFO] Redoc CLI is already installed."
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
if [ $? != 0 ]; then
echo "[ERROR] Failed to execute the Redoc CLI command form MGMT API."
exit 1
else
echo "[INFO] Successfully executed the Redoc CLI command for MGMT API."
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
if [ $? != 0 ]; then
echo "[ERROR] Failed to execute the Redoc CLI command form DDI API."
exit 1
else
echo "[INFO] Successfully executed the Redoc CLI command for DDI API."
fi

1
docs/cleanup.sh
View File

@@ -20,6 +20,7 @@ echo "[INFO] ... done"
echo "[INFO] "
echo "[INFO] Remove generated REST docs"
rm -f content/rest-api/*.json
rm -f content/rest-api/*.html
echo "[INFO] ... done"

3
docs/content/apis/ddi_api.md
View File

@@ -31,5 +31,6 @@ PROCEEDING | This can be used by the target to inform that it i
SCHEDULED | This can be used by the target to inform that it scheduled on the action. | RUNNING
RESUMED | This can be used by the target to inform that it continued to work on the action. | RUNNING
## DDI APIs
<iframe width="100%" height="800px" frameborder="0" src="../../rest-api/rootcontroller-api-guide.html"></iframe>
<iframe style="padding-top: 20px;" width="100%" height="900px" frameborder="0" src="../../rest-api/ddi.html"></iframe>

21
docs/content/apis/management_api.md
View File

@@ -26,22 +26,6 @@ Supported HTTP-methods are:
- PUT
- DELETE
Available Management APIs resources are:
- [Targets](/hawkbit/apis/mgmt/targets/)
- [Target types](/hawkbit/apis/mgmt/targettypes/)
- [Distribution sets](/hawkbit/apis/mgmt/distributionsets/)
- [Distribution set types](/hawkbit/apis/mgmt/distributionsettypes/)
- [Software modules](/hawkbit/apis/mgmt/softwaremodules/)
- [Software module types](/hawkbit/apis/mgmt/softwaremoduletypes/)
- [Target tag](/hawkbit/apis/mgmt/targettag/)
- [Distribution set tag](/hawkbit/apis/mgmt/distributionsettag/)
- [Rollouts](/hawkbit/apis/mgmt/rollouts/)
- [Actions](/hawkbit/apis/mgmt/actions/)
- [Target filters](/hawkbit/apis/mgmt/targetfilters/)
- [System configuration](/hawkbit/apis/mgmt/tenant/)
## Headers
For all requests an `Authorization` header has to be set.
@@ -78,3 +62,8 @@ A _Distribution Set_ entity may have for example URIs to artifacts, _Software Mo
"href": "http://localhost:8080/rest/v1/softwaremodules/83/metadata?offset=0&limit=50"
}
```
## Management APIs
<iframe style="padding-top: 20px;" width="100%" height="900px" frameborder="0" src="../../rest-api/mgmt.html"></iframe>

7
docs/content/apis/mgmt/actions.md
View File

@@ -1,7 +0,0 @@
---
title: Actions API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/actions-api-guide.html"></iframe>

7
docs/content/apis/mgmt/distributionsets.md
View File

@@ -1,7 +0,0 @@
---
title: Distribution Sets API
parent: Management API
weight: -101
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsets-api-guide.html"></iframe>

7
docs/content/apis/mgmt/distributionsettag.md
View File

@@ -1,7 +0,0 @@
---
title: Distribution Set Tag API
parent: Management API
weight: -105
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsettag-api-guide.html"></iframe>

7
docs/content/apis/mgmt/distributionsettypes.md
View File

@@ -1,7 +0,0 @@
---
title: Distribution Set Types API
parent: Management API
weight: -102
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/distributionsettypes-api-guide.html"></iframe>

7
docs/content/apis/mgmt/rollouts.md
View File

@@ -1,7 +0,0 @@
---
title: Rollouts API
parent: Management API
weight: -106
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/rollout-api-guide.html"></iframe>

7
docs/content/apis/mgmt/softwaremodules.md
View File

@@ -1,7 +0,0 @@
---
title: Software Modules API
parent: Management API
weight: -103
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/softwaremodules-api-guide.html"></iframe>

7
docs/content/apis/mgmt/softwaremoduletypes.md
View File

@@ -1,7 +0,0 @@
---
title: Software Module Types API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/softwaremoduletypes-api-guide.html"></iframe>

7
docs/content/apis/mgmt/targetfilters.md
View File

@@ -1,7 +0,0 @@
---
title: Target Filters API
parent: Management API
weight: -107
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targetfilters-api-guide.html"></iframe>

7
docs/content/apis/mgmt/targets.md
View File

@@ -1,7 +0,0 @@
---
title: Targets API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targets-api-guide.html"></iframe>

7
docs/content/apis/mgmt/targettag.md
View File

@@ -1,7 +0,0 @@
---
title: Target Tag API
parent: Management API
weight: -104
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targettag-api-guide.html"></iframe>

7
docs/content/apis/mgmt/targettypes.md
View File

@@ -1,7 +0,0 @@
---
title: Target Types API
parent: Management API
weight: -100
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/targettypes-api-guide.html"></iframe>

7
docs/content/apis/mgmt/tenant.md
View File

@@ -1,7 +0,0 @@
---
title: System Configuration API
parent: Management API
weight: -108
---
<iframe width="100%" height="800px" frameborder="0" src="../../../rest-api/tenant-api-guide.html"></iframe>

15
docs/install-theme.sh
View File

@@ -8,11 +8,9 @@
# SPDX-License-Identifier: EPL-2.0
#
# This script checks if 'hugo' is installed. Afterwards, the Hugo theme is downloaded.
#!/bin/bash
# This script checks if 'hugo' is installed. Afterwards, the Hugo theme is downloaded.
hugo version
if [ $? != 0 ]
then
@@ -23,6 +21,7 @@ fi
echo "[INFO] "
echo "[INFO] Install Hugo Theme"
HUGO_THEMES=themes/hugo-material-docs
CSS_FILE=themes/hugo-material-docs/static/stylesheets/application.css
if [ ! -d ${HUGO_THEMES} ]
then
@@ -32,6 +31,16 @@ else
echo "[INFO] ... theme already installed in: ${HUGO_THEMES}"
fi
# This script uses 'awk' to replace 1200px with 1500px in the application.css file from 'hugo'
if [ -f ${CSS_FILE} ]
then
awk '{gsub(/max-width:1200px/, "max-width:1500px"); print}' "${CSS_FILE}" > tmp && mv tmp "${CSS_FILE}"
echo "[INFO] Updated CSS content successfully!"
else
echo "[ERROR] CSS file not found!"
fi
echo "[INFO] "
echo "[INFO] Launch the documentation locally by running 'mvn site' (or 'hugo server' in the docs directory),"
echo "[INFO] and browse to 'http://localhost:1313/hawkbit/'. "

43
docs/pom.xml
View File

@@ -61,21 +61,22 @@
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>unpack-api-docs</id>
<id>copy-openapi</id>
<phase>prepare-package</phase>
<goals>
<goal>unpack</goal>
<goal>copy</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-rest-docs</artifactId>
<artifactId>hawkbit-update-server</artifactId>
<version>${project.version}</version>
<type>jar</type>
<classifier>openapi</classifier>
<type>json</type>
<overWrite>true</overWrite>
<outputDirectory>${basedir}/content/</outputDirectory>
<includes>**/*.html</includes>
<outputDirectory>${basedir}/content/rest-api</outputDirectory>
<destFileName>openapi.json</destFileName>
</artifactItem>
</artifactItems>
</configuration>
@@ -87,6 +88,36 @@
<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>
<goal>exec</goal>
</goals>
<phase>install</phase>
<configuration>
<executable>${shell}</executable>
<workingDirectory>${project.basedir}</workingDirectory>
<arguments>
<argument>${shell.option}</argument>
<argument>build-htmls.${batch.ext}</argument>
</arguments>
</configuration>
</execution>
<execution>
<id>install-hugo-theme</id>
<goals>

52
docs/split-doc.sh Normal file
View File

@@ -0,0 +1,52 @@
#
# Copyright (c) 2018 Bosch Software Innovations GmbH and others
#
# This program and the accompanying materials are made
# available under the terms of the Eclipse Public License 2.0
# which is available at https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
#
#!/bin/bash
CURRENT_DIR=$(pwd)
input_file=${CURRENT_DIR}/content/rest-api/openapi.json
mgmt_file=${CURRENT_DIR}/content/rest-api/mgmt.json
ddi_file=${CURRENT_DIR}/content/rest-api/ddi.json
jq '
.paths |= with_entries(
select(
reduce .value[] as $item (
false;
. or ($item.tags? | index("DDI Root Controller")) == null
)
)
)
| .tags |= map(select(.name | contains("DDI") | not))
| .components.schemas = (.components.schemas | with_entries(select(.key | startswith("Ddi") | not)))
' "$input_file" > "$mgmt_file"
jq '
.paths |= with_entries(
select(
reduce .value[] as $item (
false;
. or ($item.tags? | index("DDI Root Controller")) != null
)
)
)
| .tags |= map(select(.name | contains("DDI")))
| .components.schemas = (
.components.schemas
| with_entries(
select(
(.key | startswith("Ddi"))
or (.key | . == "Link")
or (.key | . == "ExceptionInfo")
)
)
)
' "$input_file" > "$ddi_file"

1
docs/themes/hugo-material-docs vendored Submodule

Submodule docs/themes/hugo-material-docs added at 9dbd25cf94

241
hawkbit-runtime/hawkbit-update-server/pom.xml
View File

@@ -10,101 +10,154 @@
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-runtime-parent</artifactId>
<version>0.3.0-SNAPSHOT</version>
</parent>
<artifactId>hawkbit-update-server</artifactId>
<name>hawkBit :: Runtime :: Update Server</name>
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-runtime-parent</artifactId>
<version>0.3.0-SNAPSHOT</version>
</parent>
<artifactId>hawkbit-update-server</artifactId>
<name>hawkBit :: Runtime :: Update Server</name>
<profiles>
<profile>
<id>docker</id>
<build>
<plugins>
<plugin>
<groupId>io.fabric8</groupId>
<artifactId>docker-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<build>
<plugins>
<plugin>
<profiles>
<profile>
<id>docker</id>
<build>
<plugins>
<plugin>
<groupId>io.fabric8</groupId>
<artifactId>docker-maven-plugin</artifactId>
</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>
</goals>
<configuration>
<outputDirectory>${baseDir}</outputDirectory>
<mainClass>org.eclipse.hawkbit.app.Start</mainClass>
<layout>JAR</layout>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
<resources>
<resource>
<directory>src/main/resources</directory>
</resource>
</resources>
</build>
<dependencies>
<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-boot-starter</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
</dependency>
<dependency>
<groupId>com.microsoft.sqlserver</groupId>
<artifactId>mssql-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
</dependency>
<!-- Test -->
<dependency>
<groupId>io.qameta.allure</groupId>
<artifactId>allure-junit5</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
<configuration>
<outputDirectory>${baseDir}</outputDirectory>
<mainClass>org.eclipse.hawkbit.app.Start</mainClass>
<layout>JAR</layout>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
<resources>
<resource>
<directory>src/main/resources</directory>
</resource>
</resources>
</build>
<dependencies>
<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-boot-starter</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
</dependency>
<dependency>
<groupId>com.microsoft.sqlserver</groupId>
<artifactId>mssql-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
</dependency>
<!-- Test -->
<dependency>
<groupId>io.qameta.allure</groupId>
<artifactId>allure-junit5</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.mariadb.jdbc</groupId>
<artifactId>mariadb-java-client</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-repository-test</artifactId>
<version>${project.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.mariadb.jdbc</groupId>
<artifactId>mariadb-java-client</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-repository-test</artifactId>
<version>${project.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>