lingwei.kong/hawkbit
1
0
Fork 0
Code Issues Pull Requests Actions 3 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>

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

@@ -1,10 +1,10 @@
---
---
title: Management API
parent: API
weight: 81
---
The Management API is a RESTful API that enables to perform Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. software).
The Management API is a RESTful API that enables to perform Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. software).
<!--more-->
Based on the Management API you can manage and monitor software update operations via HTTP/HTTPS. The _Management API_ supports JSON payload with hypermedia as well as filtering, sorting and paging. Furthermore the Management API provides permission based access control and standard roles as well as custom role creation.
@@ -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.
@@ -77,4 +61,9 @@ A _Distribution Set_ entity may have for example URIs to artifacts, _Software Mo
"metadata": {
"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>