From b362698af8feec33ae5f83cca42ac461372c9577 Mon Sep 17 00:00:00 2001 From: Avgustin Marinov Date: Wed, 29 Nov 2023 09:52:40 +0200 Subject: [PATCH] Move REST API Doc build in docs/ (#1492) Signed-off-by: Marinov Avgustin --- docs/.gitignore | 4 +- docs/content/rest-api/_index.md | 0 docs/pom.xml | 67 ++++++++--------- .../java/org/eclipse/hawkbit/doc/Start.java | 38 ++++++++++ .../src/main/resources/application.properties | 41 +++++++++++ docs/src/main/resources/banner.txt | 14 ++++ docs/src/main/resources/logback-spring.xml | 33 +++++++++ .../eclipse/hawkbit/doc}/RestApiDocTest.java | 72 +++++++++---------- hawkbit-runtime/hawkbit-update-server/pom.xml | 50 ------------- 9 files changed, 192 insertions(+), 127 deletions(-) delete mode 100644 docs/content/rest-api/_index.md create mode 100644 docs/src/main/java/org/eclipse/hawkbit/doc/Start.java create mode 100644 docs/src/main/resources/application.properties create mode 100644 docs/src/main/resources/banner.txt create mode 100644 docs/src/main/resources/logback-spring.xml rename {hawkbit-runtime/hawkbit-update-server/src/test/java/org/eclipse/hawkbit/app => docs/src/test/java/org/eclipse/hawkbit/doc}/RestApiDocTest.java (58%) diff --git a/docs/.gitignore b/docs/.gitignore index 3d96bdc10..88e4c850e 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -6,8 +6,8 @@ content/rest-api/*.yaml node_modules package.json package-lock.json -# themse -themes +# themes +themes/hugo-material-docs # hugo public .hugo_build.lock diff --git a/docs/content/rest-api/_index.md b/docs/content/rest-api/_index.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/pom.xml b/docs/pom.xml index 94c864be9..a177c56cf 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -1,6 +1,6 @@ hawkBit :: Documentation Documentation for hawkBit @@ -56,43 +57,6 @@ - - org.apache.maven.plugins - maven-dependency-plugin - - - copy-openapi - prepare-package - - copy - - - - - org.eclipse.hawkbit - hawkbit-update-server - ${project.version} - mgmt-openapi - yaml - true - ${basedir}/content/rest-api - mgmt.yaml - - - org.eclipse.hawkbit - hawkbit-update-server - ${project.version} - ddi-openapi - yaml - true - ${basedir}/content/rest-api - ddi.yaml - - - - - - org.codehaus.mojo exec-maven-plugin @@ -162,4 +126,29 @@ + + + org.eclipse.hawkbit + hawkbit-boot-starter + ${project.version} + + + + + io.qameta.allure + allure-junit5 + test + + + org.springframework.boot + spring-boot-starter-test + test + + + org.eclipse.hawkbit + hawkbit-repository-test + ${project.version} + test + + \ No newline at end of file diff --git a/docs/src/main/java/org/eclipse/hawkbit/doc/Start.java b/docs/src/main/java/org/eclipse/hawkbit/doc/Start.java new file mode 100644 index 000000000..4ea2ccb91 --- /dev/null +++ b/docs/src/main/java/org/eclipse/hawkbit/doc/Start.java @@ -0,0 +1,38 @@ +/** + * Copyright (c) 2023 Bosch.IO 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 + */ +package org.eclipse.hawkbit.doc; + +import org.eclipse.hawkbit.autoconfigure.security.EnableHawkbitManagedSecurityConfiguration; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; + +/** + * A {@link SpringBootApplication} annotated class with a main method to start. + * The minimal configuration for the stand alone hawkBit server. + * + */ +@SpringBootApplication +@EnableHawkbitManagedSecurityConfiguration +// Exception squid:S1118 - Spring boot standard behavior +@SuppressWarnings({ "squid:S1118" }) +public class Start { + + /** + * Main method to start the spring-boot application. + * + * @param args + * the VM arguments. + */ + // Exception squid:S2095 - Spring boot standard behavior + @SuppressWarnings({ "squid:S2095" }) + public static void main(final String[] args) { + SpringApplication.run(Start.class, args); + } +} diff --git a/docs/src/main/resources/application.properties b/docs/src/main/resources/application.properties new file mode 100644 index 000000000..be7b5d3b1 --- /dev/null +++ b/docs/src/main/resources/application.properties @@ -0,0 +1,41 @@ +# +# Copyright (c) 2023 Bosch.IO 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 +# + +# User Security +spring.security.user.name=admin +spring.security.user.password={noop}admin +spring.main.allow-bean-definition-overriding=true + +# Http Encoding +server.servlet.encoding.charset=UTF-8 +server.servlet.encoding.enabled=true +server.servlet.encoding.force=true + +# DDI authentication configuration +hawkbit.server.ddi.security.authentication.anonymous.enabled=false +hawkbit.server.ddi.security.authentication.targettoken.enabled=false +hawkbit.server.ddi.security.authentication.gatewaytoken.enabled=false + +# Optional events +hawkbit.server.repository.publish-target-poll-event=false + +## Configuration for DMF/RabbitMQ integration +hawkbit.dmf.rabbitmq.enabled=false + +# Swagger Configuration + +#springdoc.swagger-ui.path=/update-server-documentation +#springdoc.api-docs.path=/update-server-api-docs +springdoc.show-oauth2-endpoints=true +springdoc.api-docs.version=openapi_3_0 +springdoc.show-login-endpoint=true +springdoc.packages-to-scan=org.eclipse.hawkbit.mgmt,org.eclipse.hawkbit.ddi +springdoc.swagger-ui.oauth2RedirectUrl=/login/oauth2/code/suite +springdoc.paths-to-exclude=/system/** \ No newline at end of file diff --git a/docs/src/main/resources/banner.txt b/docs/src/main/resources/banner.txt new file mode 100644 index 000000000..fca127758 --- /dev/null +++ b/docs/src/main/resources/banner.txt @@ -0,0 +1,14 @@ + ______ _ _ _ _ ____ _ _ + | ____| | (_) | | | | | _ \(_) | + | |__ ___| |_ _ __ ___ ___ | |__ __ ___ _| | _| |_) |_| |_ + | __| / __| | | '_ \/ __|/ _ \ | '_ \ / _` \ \ /\ / / |/ / _ <| | __| + | |___| (__| | | |_) \__ \ __/ | | | | (_| |\ V V /| <| |_) | | |_ + |______\___|_|_| .__/|___/\___| |_| |_|\__,_| \_/\_/ |_|\_\____/|_|\__| + | | + |_| + +Eclipse hawkBit Update Server ${application.formatted-version} +using Spring Boot ${spring-boot.formatted-version} + +Go to https://www.eclipse.org/hawkbit for more information. + \ No newline at end of file diff --git a/docs/src/main/resources/logback-spring.xml b/docs/src/main/resources/logback-spring.xml new file mode 100644 index 000000000..b71e34118 --- /dev/null +++ b/docs/src/main/resources/logback-spring.xml @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/hawkbit-runtime/hawkbit-update-server/src/test/java/org/eclipse/hawkbit/app/RestApiDocTest.java b/docs/src/test/java/org/eclipse/hawkbit/doc/RestApiDocTest.java similarity index 58% rename from hawkbit-runtime/hawkbit-update-server/src/test/java/org/eclipse/hawkbit/app/RestApiDocTest.java rename to docs/src/test/java/org/eclipse/hawkbit/doc/RestApiDocTest.java index 990a64593..f50646e28 100644 --- a/hawkbit-runtime/hawkbit-update-server/src/test/java/org/eclipse/hawkbit/app/RestApiDocTest.java +++ b/docs/src/test/java/org/eclipse/hawkbit/doc/RestApiDocTest.java @@ -8,7 +8,7 @@ * SPDX-License-Identifier: EPL-2.0 */ -package org.eclipse.hawkbit.app; +package org.eclipse.hawkbit.doc; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.dataformat.yaml.YAMLMapper; @@ -36,9 +36,11 @@ import static org.assertj.core.api.Assertions.assertThat; @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @ExtendWith({SharedSqlTestDatabaseExtension.class}) class RestApiDocTest { - private static final String MANAGEMENT_PREFIX = "mgmt-openapi"; - private static final String DDI_PREFIX = "ddi-openapi"; - private static final String TARGET_DIRECTORY = "target/rest-api/"; + private static final String MANAGEMENT_PREFIX = "mgmt"; + private static final String DDI_PREFIX = "ddi"; + private static final String TARGET_DIRECTORY = "content/rest-api/"; + + private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper(); @LocalServerPort private int port; @@ -46,39 +48,37 @@ class RestApiDocTest { @Autowired private TestRestTemplate restTemplate; - private final ObjectMapper objectMapper = new ObjectMapper(); - @Test void openapiJson() throws IOException { - ResponseEntity response = + final ResponseEntity response = restTemplate.getForEntity("http://localhost:" + port + "/v3/api-docs", String.class); - String openapiDoc = response.getBody(); + final String openapiDoc = response.getBody(); assertThat(openapiDoc).isNotNull(); splitDocumentation(openapiDoc); } - private void splitDocumentation(String json) throws IOException { + private static void splitDocumentation(final String json) throws IOException { processDocumentation(json, true); processDocumentation(json, false); } - private void processDocumentation(String json, boolean isMgmt) throws IOException { - JsonNode rootNode = objectMapper.readTree(json); + private static void processDocumentation(final String json, final boolean isMgmt) throws IOException { + final JsonNode rootNode = OBJECT_MAPPER.readTree(json); updateJsonNodeForApi(rootNode, isMgmt); saveDocumentation(rootNode, isMgmt); } - private void updateJsonNodeForApi(JsonNode rootNode, boolean isMgmt) { + private static void updateJsonNodeForApi(final JsonNode rootNode, final boolean isMgmt) { removeTags(rootNode, isMgmt); removePaths(rootNode, isMgmt); removeComponents(rootNode, isMgmt); } - private void removeTags(JsonNode rootNode, boolean isMgmt) { - ArrayNode tagsNode = (ArrayNode) rootNode.get("tags"); - ArrayNode modifiedTagsNode = objectMapper.createArrayNode(); + private static void removeTags(final JsonNode rootNode, final boolean isMgmt) { + final ArrayNode tagsNode = (ArrayNode) rootNode.get("tags"); + final ArrayNode modifiedTagsNode = OBJECT_MAPPER.createArrayNode(); - for (JsonNode tagNode : tagsNode) { + for (final JsonNode tagNode : tagsNode) { String tagName = tagNode.get("name").asText(); if (isMgmt != tagName.startsWith("DDI")) { modifiedTagsNode.add(tagNode); @@ -87,17 +87,17 @@ class RestApiDocTest { ((ObjectNode) rootNode).set("tags", modifiedTagsNode); } - private void removePaths(JsonNode rootNode, boolean isMgmt) { - ObjectNode pathsNode = (ObjectNode) rootNode.get("paths"); - List fieldsToRemove = new ArrayList<>(); + private static void removePaths(final JsonNode rootNode, final boolean isMgmt) { + final ObjectNode pathsNode = (ObjectNode) rootNode.get("paths"); + final List fieldsToRemove = new ArrayList<>(); pathsNode.fieldNames().forEachRemaining(fieldName -> { - JsonNode pathNode = pathsNode.get(fieldName); + final JsonNode pathNode = pathsNode.get(fieldName); pathNode.fieldNames().forEachRemaining(path -> { - JsonNode methodNode = pathNode.get(path); - JsonNode tagsNode = methodNode.get("tags"); + final JsonNode methodNode = pathNode.get(path); + final JsonNode tagsNode = methodNode.get("tags"); if (tagsNode != null) { for (JsonNode tagNode : tagsNode) { - String tag = tagNode.asText(); + final String tag = tagNode.asText(); if (isMgmt == tag.startsWith("DDI")) { fieldsToRemove.add(fieldName); break; @@ -109,8 +109,8 @@ class RestApiDocTest { fieldsToRemove.forEach(pathsNode::remove); } - private void removeComponents(JsonNode rootNode, boolean isMgmt) { - ObjectNode schemasNode = (ObjectNode) rootNode.get("components").get("schemas"); + private static void removeComponents(final JsonNode rootNode, final boolean isMgmt) { + final ObjectNode schemasNode = (ObjectNode) rootNode.get("components").get("schemas"); List fieldsToRemove = new ArrayList<>(); schemasNode.fieldNames().forEachRemaining(fieldName -> { @@ -121,7 +121,7 @@ class RestApiDocTest { fieldsToRemove.forEach(schemasNode::remove); } - private boolean shouldDeleteComponent(String fieldName, boolean isMgmt) { + private static boolean shouldDeleteComponent(final String fieldName, final boolean isMgmt) { if (isMgmt) { return fieldName.startsWith("Ddi"); } @@ -129,25 +129,25 @@ class RestApiDocTest { } - private void saveDocumentation(JsonNode rootNode, boolean isMgmt) throws IOException { - String prefix = isMgmt ? MANAGEMENT_PREFIX : DDI_PREFIX; + private static void saveDocumentation(final JsonNode rootNode, final boolean isMgmt) throws IOException { + final String prefix = isMgmt ? MANAGEMENT_PREFIX : DDI_PREFIX; saveAsJson(rootNode, prefix); saveAsYaml(rootNode, prefix); } - private void saveAsJson(JsonNode rootNode, String prefix) throws IOException { - Path targetPath = getTargetPath(prefix, ".json"); - Files.writeString(targetPath, objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(rootNode)); + private static void saveAsJson(final JsonNode rootNode, final String prefix) throws IOException { + final Path targetPath = getTargetPath(prefix, ".json"); + Files.writeString(targetPath, OBJECT_MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(rootNode)); } - private void saveAsYaml(JsonNode rootNode, String prefix) throws IOException { - YAMLMapper yamlMapper = new YAMLMapper(); - Path targetPath = getTargetPath(prefix, ".yaml"); + private static void saveAsYaml(final JsonNode rootNode, final String prefix) throws IOException { + final YAMLMapper yamlMapper = new YAMLMapper(); + final Path targetPath = getTargetPath(prefix, ".yaml"); Files.writeString(targetPath, yamlMapper.writeValueAsString(rootNode)); } - private Path getTargetPath(String prefix, String extension) throws IOException { - Path targetPath = Paths.get(TARGET_DIRECTORY + prefix + extension); + private static Path getTargetPath(final String prefix, final String extension) throws IOException { + final Path targetPath = Paths.get(TARGET_DIRECTORY + prefix + extension); Files.createDirectories(targetPath.getParent()); return targetPath; } diff --git a/hawkbit-runtime/hawkbit-update-server/pom.xml b/hawkbit-runtime/hawkbit-update-server/pom.xml index f097b7085..b28781576 100644 --- a/hawkbit-runtime/hawkbit-update-server/pom.xml +++ b/hawkbit-runtime/hawkbit-update-server/pom.xml @@ -32,56 +32,6 @@ - - attach-artifacts-profile - - - - !skipTests - - - - - - org.codehaus.mojo - build-helper-maven-plugin - - - attach-artifacts - package - - attach-artifact - - - - - ${project.build.directory}/rest-api/mgmt-openapi.json - json - mgmt-openapi - - - ${project.build.directory}/rest-api/mgmt-openapi.yaml - yaml - mgmt-openapi - - - ${project.build.directory}/rest-api/ddi-openapi.json - json - ddi-openapi - - - ${project.build.directory}/rest-api/ddi-openapi.yaml - yaml - ddi-openapi - - - - - - - - -