Chore/improve api docs generation (#4190)
* chore: getswagger quality-of-life - Exit on invalid options. - Show curl output, e.g. if the filepath is incorrect. - Replace $_ with $outFile for readability. - Replace context with platform, the common jargon. * chore(api): generate.sh quality-of-life - Only regenerate HTML for a spec version if the current file differs from master. - Refactor to remove code repetition.pull/4194/head
Jason Stirnaman
GitHub
parent
d9d30d093b
commit
ee7239189c
|
|
@ -2,6 +2,51 @@
|
|||
|
||||
set -e
|
||||
|
||||
function buildHugoTemplate {
|
||||
version=$1
|
||||
apiVersion=$2
|
||||
module1=$3
|
||||
|
||||
V_LEN_INIT=$(wc -c $version$module1.tmp | awk '{print $1}')
|
||||
cat "redoc-static${module1}.html" >> $version$module1.tmp
|
||||
V_LEN=$(wc -c $version$module1.tmp | awk '{print $1}')
|
||||
|
||||
if ! [[ $V_LEN -gt $V_LEN_INIT ]]
|
||||
then
|
||||
echo "Error: bundle was not appended to $version$module1.tmp"
|
||||
exit $?
|
||||
fi
|
||||
|
||||
rm -f "redoc-static${module1}.html"
|
||||
mkdir -p ../content/influxdb/$version/api
|
||||
}
|
||||
|
||||
function generateHtml {
|
||||
filePath=$1
|
||||
titleVersion=$2
|
||||
submodule=$3
|
||||
titleSubmodule=$4
|
||||
|
||||
echo "Bundling $filePath"
|
||||
|
||||
npx --version
|
||||
|
||||
# Use npx to install and run the specified version of redoc-cli.
|
||||
# npm_config_yes=true npx overrides the prompt
|
||||
# and (vs. npx --yes) is compatible with npm@6 and npm@7.
|
||||
npm_config_yes=true npx redoc-cli@0.12.3 bundle $filePath \
|
||||
-t template.hbs \
|
||||
--title="InfluxDB $titleVersion$titleSubmodule API documentation" \
|
||||
--options.sortPropsAlphabetically \
|
||||
--options.menuToggle \
|
||||
--options.hideDownloadButton \
|
||||
--options.hideHostname \
|
||||
--options.noAutoAuth \
|
||||
--templateOptions.version="$version" \
|
||||
--templateOptions.titleVersion="$titleVersion" \
|
||||
--output="redoc-static$submodule.html"
|
||||
}
|
||||
|
||||
# Get list of versions from directory names
|
||||
versions="$(ls -d -- */ | grep -v 'node_modules' | grep -v 'openapi')"
|
||||
|
||||
|
|
@ -29,7 +74,7 @@ menu:
|
|||
weight: 102
|
||||
---
|
||||
"
|
||||
v1frontmatter="---
|
||||
v1compatfrontmatter="---
|
||||
title: InfluxDB $titleVersion v1 compatibility API documentation
|
||||
description: >
|
||||
The InfluxDB v1 compatibility API provides a programmatic interface for interactions with InfluxDB $titleVersion using InfluxDB v1.x compatibility endpoints.
|
||||
|
|
@ -42,70 +87,31 @@ weight: 304
|
|||
---
|
||||
"
|
||||
|
||||
# Use npx to install and run the specified version of redoc-cli.
|
||||
# npm_config_yes=true npx overrides the prompt
|
||||
# and (vs. npx --yes) is compatible with npm@6 and npm@7.
|
||||
# If the v2 spec file differs from master, regenerate the HTML.
|
||||
filePath="${version}/ref.yml"
|
||||
fileChanged=$(git diff --name-status master -- ${filePath})
|
||||
if [ ! -z "$fileChanged" ]; then
|
||||
submodule=""
|
||||
titleSubmodule=""
|
||||
generateHtml $filePath $titleVersion $submodule $titleSubmodule
|
||||
|
||||
redocCLI="redoc-cli@0.12.3"
|
||||
|
||||
npx --version
|
||||
|
||||
# Use Redoc to generate the v2 API html
|
||||
echo "Bundling ${version}/ref.yml"
|
||||
npm_config_yes=true npx $redocCLI bundle $version/ref.yml \
|
||||
-t template.hbs \
|
||||
--title="InfluxDB $titleVersion API documentation" \
|
||||
--options.sortPropsAlphabetically \
|
||||
--options.menuToggle \
|
||||
--options.hideHostname \
|
||||
--options.hideDownloadButton \
|
||||
--options.noAutoAuth \
|
||||
--templateOptions.version="$version" \
|
||||
--templateOptions.titleVersion="$titleVersion" \
|
||||
|
||||
# Use Redoc to generate the v1 compatibility API html
|
||||
echo "Bundling ${version}/swaggerV1Compat.yml"
|
||||
npm_config_yes=true npx $redocCLI bundle $version/swaggerV1Compat.yml \
|
||||
-t template.hbs \
|
||||
--title="InfluxDB $titleVersion v1 compatibility API documentation" \
|
||||
--options.sortPropsAlphabetically \
|
||||
--options.menuToggle \
|
||||
--options.hideDownloadButton \
|
||||
--options.hideHostname \
|
||||
--options.noAutoAuth \
|
||||
--templateOptions.version="$version" \
|
||||
--templateOptions.titleVersion="$titleVersion" \
|
||||
--output=redoc-static-v1-compat.html \
|
||||
|
||||
# Create temp file with frontmatter and Redoc html
|
||||
echo "$v2frontmatter" >> $version.tmp
|
||||
echo "$v1frontmatter" >> $version-v1-compat.tmp
|
||||
|
||||
V2LEN_INIT=$(wc -c $version.tmp | awk '{print $1}')
|
||||
V1LEN_INIT=$(wc -c $version-v1-compat.tmp | awk '{print $1}')
|
||||
|
||||
cat redoc-static.html >> $version.tmp
|
||||
cat redoc-static-v1-compat.html >> $version-v1-compat.tmp
|
||||
|
||||
V2LEN=$(wc -c $version.tmp | awk '{print $1}')
|
||||
V1LEN=$(wc -c $version-v1-compat.tmp | awk '{print $1}')
|
||||
|
||||
if ! [[ $V2LEN -gt $V2LEN_INIT ]]
|
||||
then
|
||||
echo "Error: bundle was not appended to $version.tmp"
|
||||
exit $?
|
||||
# Create temp file with frontmatter and Redoc html
|
||||
echo "$v2frontmatter" >> $version.tmp
|
||||
buildHugoTemplate $version v2 $submodule && \
|
||||
mv $version.tmp ../content/influxdb/$version/api/_index.html
|
||||
fi
|
||||
|
||||
if ! [[ $V1LEN -gt $V1LEN_INIT ]]
|
||||
then
|
||||
echo "Error: bundle was not appended to $version-v1-compat.tmp"
|
||||
exit $?
|
||||
fi
|
||||
# If the v1 compatibility spec file differs from master, regenerate the HTML.
|
||||
filePath="${version}/swaggerV1Compat.yml"
|
||||
fileChanged=$(git diff --name-status master -- ${filePath})
|
||||
if [ ! -z "$fileChanged" ]; then
|
||||
submodule="-v1-compat"
|
||||
titleSubmodule="v1 compatibility"
|
||||
generateHtml $filePath $titleVersion $submodule $titleSubmodule
|
||||
|
||||
# Remove redoc file and move the tmp file to it's proper place
|
||||
rm -f redoc-static.html
|
||||
rm -f redoc-static-v1-compat.html
|
||||
mkdir -p ../content/influxdb/$version/api
|
||||
mv $version.tmp ../content/influxdb/$version/api/_index.html
|
||||
mv $version-v1-compat.tmp ../content/influxdb/$version/api/v1-compatibility.html
|
||||
# Create temp file with frontmatter and Redoc html
|
||||
echo "$v1compatfrontmatter" >> $version$submodule.tmp
|
||||
buildHugoTemplate $version v1 $submodule && \
|
||||
mv $version$submodule.tmp ../content/influxdb/$version/api/v1-compatibility.html
|
||||
fi
|
||||
done
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
# This script provides a simple way grab the latest fully resolved openapi (OAS, OpenAPI Specification) contract files
|
||||
# from the influxdata/openapi repo.
|
||||
#
|
||||
# Specify a context to retrieve (cloud, oss, v1compat, all).
|
||||
# Specify a platform to retrieve (cloud, oss, v1compat, all).
|
||||
# Optionally specify:
|
||||
# - an OSS version as the second argument or using the -o flag.
|
||||
# The version specifies where to write the updated openapi.
|
||||
|
|
@ -15,9 +15,9 @@
|
|||
# For local development, pass your openapi directory using the file:/// protocol.
|
||||
#
|
||||
# Syntax:
|
||||
# sh ./getswagger.sh <context>
|
||||
# sh ./getswagger.sh <context> -b <baseUrl>
|
||||
# sh ./getswagger.sh -c <context> -o <version> -b <baseUrl>
|
||||
# sh ./getswagger.sh <platform>
|
||||
# sh ./getswagger.sh <platform> -b <baseUrl>
|
||||
# sh ./getswagger.sh -c <platform> -o <version> -b <baseUrl>
|
||||
#
|
||||
# Examples:
|
||||
# sh ./getswagger.sh cloud
|
||||
|
|
@ -33,13 +33,15 @@ baseUrl="https://raw.githubusercontent.com/influxdata/openapi/master"
|
|||
baseUrlOSS="https://raw.githubusercontent.com/influxdata/openapi/docs-release/influxdb-oss"
|
||||
ossVersion=${latestOSS%/}
|
||||
verbose=""
|
||||
context=""
|
||||
platform=""
|
||||
|
||||
function showHelp {
|
||||
echo "Usage: ./getswagger.sh <context>"
|
||||
echo "Usage: ./getswagger.sh <platform>"
|
||||
echo " With optional arguments:"
|
||||
echo " ./getswagger.sh <context> -b <baseUrl> -V"
|
||||
echo " ./getswagger.sh <platform> -b <baseUrl> -V"
|
||||
echo " ./getswagger.sh cloud"
|
||||
echo " ./getswagger.sh oss -o <ossVersion> -V"
|
||||
echo " ./getswagger.sh all -o <ossVersion>"
|
||||
echo "Commands:"
|
||||
echo "-b <URL> The base URL to fetch from."
|
||||
echo " ex. ./getswagger.sh -b file:///Users/yourname/github/openapi"
|
||||
|
|
@ -55,7 +57,7 @@ subcommand=$1
|
|||
|
||||
case "$subcommand" in
|
||||
cloud|oss|v1compat|all)
|
||||
context=$1
|
||||
platform=$1
|
||||
shift
|
||||
|
||||
while getopts ":o:b:hV" opt; do
|
||||
|
|
@ -77,10 +79,12 @@ case "$subcommand" in
|
|||
\?)
|
||||
echo "Invalid option: $OPTARG" 1>&2
|
||||
showHelp
|
||||
exit 22
|
||||
;;
|
||||
:)
|
||||
echo "Invalid option: $OPTARG requires an argument" 1>&2
|
||||
showHelp
|
||||
exit 22
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
|
@ -89,7 +93,7 @@ case "$subcommand" in
|
|||
esac
|
||||
|
||||
function showArgs {
|
||||
echo "context: $context";
|
||||
echo "platform: $platform";
|
||||
echo "baseUrl: $baseUrl";
|
||||
echo "ossVersion: $ossVersion";
|
||||
}
|
||||
|
|
@ -116,44 +120,52 @@ function postProcess() {
|
|||
}
|
||||
|
||||
function updateCloud {
|
||||
curl ${verbose} ${baseUrl}/contracts/ref/cloud.yml -s -o cloud/ref.yml
|
||||
postProcess $_ cloud
|
||||
outFile="cloud/ref.yml"
|
||||
curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile
|
||||
postProcess $outFile cloud
|
||||
}
|
||||
|
||||
function updateOSS {
|
||||
mkdir -p ${ossVersion} && curl ${verbose} ${baseUrlOSS}/contracts/ref/oss.yml -s -o $_/ref.yml
|
||||
postProcess $_ $ossVersion
|
||||
mkdir -p ${ossVersion}
|
||||
outFile="$ossVersion/ref.yml"
|
||||
curl $UPDATE_OPTIONS ${baseUrlOSS}/contracts/ref/oss.yml -o $outFile
|
||||
postProcess $outFile $ossVersion
|
||||
}
|
||||
|
||||
function updateV1Compat {
|
||||
curl ${verbose} ${baseUrl}/contracts/swaggerV1Compat.yml -s -o cloud/swaggerV1Compat.yml
|
||||
postProcess $_ cloud v1compat
|
||||
outFile="cloud/swaggerV1Compat.yml"
|
||||
curl $UPDATE_OPTIONS ${baseUrl}/contracts/swaggerV1Compat.yml -o $outFile
|
||||
postProcess $outFile cloud v1compat
|
||||
|
||||
mkdir -p ${ossVersion} && cp cloud/swaggerV1Compat.yml $_/swaggerV1Compat.yml
|
||||
postProcess $_ $ossVersion v1compat
|
||||
outFile="$ossVersion/swaggerV1Compat.yml"
|
||||
mkdir -p ${ossVersion} && cp cloud/swaggerV1Compat.yml $outFile
|
||||
postProcess $outFile $ossVersion v1compat
|
||||
}
|
||||
|
||||
UPDATE_OPTIONS="--fail"
|
||||
|
||||
if [ ! -z ${verbose} ];
|
||||
then
|
||||
UPDATE_OPTIONS="-v $UPDATE_OPTIONS"
|
||||
showArgs
|
||||
echo ""
|
||||
fi
|
||||
|
||||
if [ "$context" = "cloud" ];
|
||||
if [ "$platform" = "cloud" ];
|
||||
then
|
||||
updateCloud
|
||||
elif [ "$context" = "oss" ];
|
||||
elif [ "$platform" = "oss" ];
|
||||
then
|
||||
updateOSS
|
||||
elif [ "$context" = "v1compat" ];
|
||||
elif [ "$platform" = "v1compat" ];
|
||||
then
|
||||
updateV1Compat
|
||||
elif [ "$context" = "all" ];
|
||||
elif [ "$platform" = "all" ];
|
||||
then
|
||||
updateCloud
|
||||
updateOSS
|
||||
updateV1Compat
|
||||
else
|
||||
echo "Provide a context (cloud, oss, v1compat, all)"
|
||||
echo "Provide a platform argument: cloud, oss, v1compat, or all."
|
||||
showHelp
|
||||
fi
|
||||
|
|
|
|||
Loading…
Reference in New Issue