From 3978454900c5a4f5000d1363a67d315652457c7e Mon Sep 17 00:00:00 2001 From: Denislav Prinov Date: Wed, 27 Sep 2023 11:44:30 +0300 Subject: [PATCH] HTTP documentation generation from OpenApi documentation (#1438) * Generating rest doc from swagger json Signed-off-by: Denislav Prinov * refactoring and adding doc Signed-off-by: Denislav Prinov * refactoring Signed-off-by: Denislav Prinov * Don't directly inject files in the executable jar since it brakes it Signed-off-by: Denislav Prinov * using the attachArtifact configuration to generate secondary artifact Signed-off-by: Denislav Prinov * Splitting the json documentation into mgmt and ddi. And some refactoring Signed-off-by: Denislav Prinov * refactoring Signed-off-by: Denislav Prinov * Split mgmt and DDI components from the json Signed-off-by: Denislav Prinov --------- Signed-off-by: Denislav Prinov --- .../apis/mgmt/_index.md => .gitmodules | 0 docs/README.md | 5 +- docs/build-htmls.sh | 44 ++++ docs/cleanup.sh | 1 + docs/content/apis/ddi_api.md | 3 +- docs/content/apis/management_api.md | 27 +- docs/content/apis/mgmt/actions.md | 7 - docs/content/apis/mgmt/distributionsets.md | 7 - docs/content/apis/mgmt/distributionsettag.md | 7 - .../content/apis/mgmt/distributionsettypes.md | 7 - docs/content/apis/mgmt/rollouts.md | 7 - docs/content/apis/mgmt/softwaremodules.md | 7 - docs/content/apis/mgmt/softwaremoduletypes.md | 7 - docs/content/apis/mgmt/targetfilters.md | 7 - docs/content/apis/mgmt/targets.md | 7 - docs/content/apis/mgmt/targettag.md | 7 - docs/content/apis/mgmt/targettypes.md | 7 - docs/content/apis/mgmt/tenant.md | 7 - docs/install-theme.sh | 15 +- docs/pom.xml | 43 +++- docs/split-doc.sh | 52 ++++ docs/themes/hugo-material-docs | 1 + hawkbit-runtime/hawkbit-update-server/pom.xml | 241 +++++++++++------- 23 files changed, 308 insertions(+), 208 deletions(-) rename docs/content/apis/mgmt/_index.md => .gitmodules (100%) create mode 100644 docs/build-htmls.sh delete mode 100644 docs/content/apis/mgmt/actions.md delete mode 100644 docs/content/apis/mgmt/distributionsets.md delete mode 100644 docs/content/apis/mgmt/distributionsettag.md delete mode 100644 docs/content/apis/mgmt/distributionsettypes.md delete mode 100644 docs/content/apis/mgmt/rollouts.md delete mode 100644 docs/content/apis/mgmt/softwaremodules.md delete mode 100644 docs/content/apis/mgmt/softwaremoduletypes.md delete mode 100644 docs/content/apis/mgmt/targetfilters.md delete mode 100644 docs/content/apis/mgmt/targets.md delete mode 100644 docs/content/apis/mgmt/targettag.md delete mode 100644 docs/content/apis/mgmt/targettypes.md delete mode 100644 docs/content/apis/mgmt/tenant.md create mode 100644 docs/split-doc.sh create mode 160000 docs/themes/hugo-material-docs diff --git a/docs/content/apis/mgmt/_index.md b/.gitmodules similarity index 100% rename from docs/content/apis/mgmt/_index.md rename to .gitmodules diff --git a/docs/README.md b/docs/README.md index 16b66d957..3f68367f8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/build-htmls.sh b/docs/build-htmls.sh new file mode 100644 index 000000000..2a103591a --- /dev/null +++ b/docs/build-htmls.sh @@ -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 \ No newline at end of file diff --git a/docs/cleanup.sh b/docs/cleanup.sh index 1fa307163..3a4d60a06 100644 --- a/docs/cleanup.sh +++ b/docs/cleanup.sh @@ -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" diff --git a/docs/content/apis/ddi_api.md b/docs/content/apis/ddi_api.md index 4cb980e48..3a7efbb66 100644 --- a/docs/content/apis/ddi_api.md +++ b/docs/content/apis/ddi_api.md @@ -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 - \ No newline at end of file + diff --git a/docs/content/apis/management_api.md b/docs/content/apis/management_api.md index b1f300daa..5070b504c 100644 --- a/docs/content/apis/management_api.md +++ b/docs/content/apis/management_api.md @@ -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). 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" } -``` \ No newline at end of file +``` + +## Management APIs + + + diff --git a/docs/content/apis/mgmt/actions.md b/docs/content/apis/mgmt/actions.md deleted file mode 100644 index 3fef85b75..000000000 --- a/docs/content/apis/mgmt/actions.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Actions API -parent: Management API -weight: -100 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/distributionsets.md b/docs/content/apis/mgmt/distributionsets.md deleted file mode 100644 index 50952749b..000000000 --- a/docs/content/apis/mgmt/distributionsets.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Distribution Sets API -parent: Management API -weight: -101 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/distributionsettag.md b/docs/content/apis/mgmt/distributionsettag.md deleted file mode 100644 index 975b87b92..000000000 --- a/docs/content/apis/mgmt/distributionsettag.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Distribution Set Tag API -parent: Management API -weight: -105 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/distributionsettypes.md b/docs/content/apis/mgmt/distributionsettypes.md deleted file mode 100644 index d9a97e3c5..000000000 --- a/docs/content/apis/mgmt/distributionsettypes.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Distribution Set Types API -parent: Management API -weight: -102 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/rollouts.md b/docs/content/apis/mgmt/rollouts.md deleted file mode 100644 index 26192da3f..000000000 --- a/docs/content/apis/mgmt/rollouts.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Rollouts API -parent: Management API -weight: -106 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/softwaremodules.md b/docs/content/apis/mgmt/softwaremodules.md deleted file mode 100644 index 3e340452f..000000000 --- a/docs/content/apis/mgmt/softwaremodules.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Software Modules API -parent: Management API -weight: -103 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/softwaremoduletypes.md b/docs/content/apis/mgmt/softwaremoduletypes.md deleted file mode 100644 index a537d4a9e..000000000 --- a/docs/content/apis/mgmt/softwaremoduletypes.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Software Module Types API -parent: Management API -weight: -100 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/targetfilters.md b/docs/content/apis/mgmt/targetfilters.md deleted file mode 100644 index 7c3e22231..000000000 --- a/docs/content/apis/mgmt/targetfilters.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Target Filters API -parent: Management API -weight: -107 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/targets.md b/docs/content/apis/mgmt/targets.md deleted file mode 100644 index 1557cf190..000000000 --- a/docs/content/apis/mgmt/targets.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Targets API -parent: Management API -weight: -100 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/targettag.md b/docs/content/apis/mgmt/targettag.md deleted file mode 100644 index 671536304..000000000 --- a/docs/content/apis/mgmt/targettag.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Target Tag API -parent: Management API -weight: -104 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/targettypes.md b/docs/content/apis/mgmt/targettypes.md deleted file mode 100644 index a641160a3..000000000 --- a/docs/content/apis/mgmt/targettypes.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Target Types API -parent: Management API -weight: -100 ---- - - \ No newline at end of file diff --git a/docs/content/apis/mgmt/tenant.md b/docs/content/apis/mgmt/tenant.md deleted file mode 100644 index e472cca53..000000000 --- a/docs/content/apis/mgmt/tenant.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: System Configuration API -parent: Management API -weight: -108 ---- - - \ No newline at end of file diff --git a/docs/install-theme.sh b/docs/install-theme.sh index 7076881f6..a78045c8c 100755 --- a/docs/install-theme.sh +++ b/docs/install-theme.sh @@ -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/'. " \ No newline at end of file diff --git a/docs/pom.xml b/docs/pom.xml index b79489378..ad9af91a1 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -61,21 +61,22 @@ maven-dependency-plugin - unpack-api-docs + copy-openapi prepare-package - unpack + copy org.eclipse.hawkbit - hawkbit-rest-docs + hawkbit-update-server ${project.version} - jar + openapi + json true - ${basedir}/content/ - **/*.html + ${basedir}/content/rest-api + openapi.json @@ -87,6 +88,36 @@ exec-maven-plugin ${exec-maven-plugin.version} + + split-docs + + exec + + install + + ${shell} + ${project.basedir} + + ${shell.option} + split-doc.${batch.ext} + + + + + build-htmls + + exec + + install + + ${shell} + ${project.basedir} + + ${shell.option} + build-htmls.${batch.ext} + + + install-hugo-theme diff --git a/docs/split-doc.sh b/docs/split-doc.sh new file mode 100644 index 000000000..9125e90f2 --- /dev/null +++ b/docs/split-doc.sh @@ -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" + diff --git a/docs/themes/hugo-material-docs b/docs/themes/hugo-material-docs new file mode 160000 index 000000000..9dbd25cf9 --- /dev/null +++ b/docs/themes/hugo-material-docs @@ -0,0 +1 @@ +Subproject commit 9dbd25cf9474f3a8bc4c09ec4c7965c8fdee9a5f diff --git a/hawkbit-runtime/hawkbit-update-server/pom.xml b/hawkbit-runtime/hawkbit-update-server/pom.xml index 5ec05f583..6b27beb3d 100644 --- a/hawkbit-runtime/hawkbit-update-server/pom.xml +++ b/hawkbit-runtime/hawkbit-update-server/pom.xml @@ -10,101 +10,154 @@ --> - 4.0.0 - - org.eclipse.hawkbit - hawkbit-runtime-parent - 0.3.0-SNAPSHOT - - hawkbit-update-server - hawkBit :: Runtime :: Update Server + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + 4.0.0 + + org.eclipse.hawkbit + hawkbit-runtime-parent + 0.3.0-SNAPSHOT + + hawkbit-update-server + hawkBit :: Runtime :: Update Server - - - docker - - - - io.fabric8 - docker-maven-plugin - - - - - - - - + + + docker + + + + io.fabric8 + docker-maven-plugin + + + + + + + + + + org.springdoc + springdoc-openapi-maven-plugin + 1.4 + + + + generate-json + integration-test + + generate + + + openapi.json + http://localhost:8080/v3/api-docs + true + + + + + generate-yaml + integration-test + + generate + + + openapi.yaml + http://localhost:8080/v3/api-docs.yaml + true + + + + + + org.springframework.boot + spring-boot-maven-plugin + + -Dspring.application.admin.enabled=true + org.eclipse.hawkbit.app.Start + + + + pre-integration-test + pre-api-docs-generation + + start + + + + post-api-docs-generation + post-integration-test + + stop + + + + + repackage + + + ${baseDir} + org.eclipse.hawkbit.app.Start + JAR + + + + + + + + + src/main/resources + + + + + + + org.eclipse.hawkbit + hawkbit-boot-starter + ${project.version} + + + com.h2database + h2 + + + com.microsoft.sqlserver + mssql-jdbc + + + org.postgresql + postgresql + + + + + io.qameta.allure + allure-junit5 + test + + org.springframework.boot - spring-boot-maven-plugin - - - - repackage - - - ${baseDir} - org.eclipse.hawkbit.app.Start - JAR - - - - - - - - src/main/resources - - - - - - - org.eclipse.hawkbit - hawkbit-boot-starter - ${project.version} - - - com.h2database - h2 - - - com.microsoft.sqlserver - mssql-jdbc - - - org.postgresql - postgresql - - - - - io.qameta.allure - allure-junit5 - test - - - org.springframework.boot - spring-boot-starter-test - test - - - org.springframework.security - spring-security-test - test - - - org.mariadb.jdbc - mariadb-java-client - test - - - org.eclipse.hawkbit - hawkbit-repository-test - ${project.version} - test - - + spring-boot-starter-test + test + + + org.springframework.security + spring-security-test + test + + + org.mariadb.jdbc + mariadb-java-client + test + + + org.eclipse.hawkbit + hawkbit-repository-test + ${project.version} + test + +