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

Openapi restdoc generation v2 (#1442)

Browse Source 
* OpenApi restdoc generation v2

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

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

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

* Add missing header

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

* Add license header

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-10-02 11:04:52 +03:00
committed by GitHub
parent 60f14691fc
commit a4204956e6
6 changed files with 222 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/README.md
View File

@@ -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

4
docs/build-htmls.sh
View File

@@ -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."
@@ -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."

31
docs/pom.xml
View File

@@ -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>
@@ -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>

52
docs/split-doc.sh
View File

@@ -1,52 +0,0 @@
#
# 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"