From e76dfb1ff483d0ba489855e0b0a9778ef080ec4a Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 8 Jul 2022 10:48:41 -0500 Subject: [PATCH] Revert "Chore/improve api docs generation (#4190)" (#4194) This reverts commit ee7239189c137759791f8319a6a3a8b0b361b971. Got 404s for API docs pages after deploy. --- api-docs/generate-api-docs.sh | 132 ++++++++++++++++------------------ api-docs/getswagger.sh | 56 ++++++--------- 2 files changed, 85 insertions(+), 103 deletions(-) diff --git a/api-docs/generate-api-docs.sh b/api-docs/generate-api-docs.sh index ed26f9372..a2dbbd46a 100755 --- a/api-docs/generate-api-docs.sh +++ b/api-docs/generate-api-docs.sh @@ -2,51 +2,6 @@ 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')" @@ -74,7 +29,7 @@ menu: weight: 102 --- " - v1compatfrontmatter="--- + v1frontmatter="--- 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. @@ -87,31 +42,70 @@ weight: 304 --- " - # 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 + # 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. - # 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 + 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 $? 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 - - # 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 + if ! [[ $V1LEN -gt $V1LEN_INIT ]] + then + echo "Error: bundle was not appended to $version-v1-compat.tmp" + exit $? fi + + # 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 done diff --git a/api-docs/getswagger.sh b/api-docs/getswagger.sh index 365ce5aa0..a55745787 100755 --- a/api-docs/getswagger.sh +++ b/api-docs/getswagger.sh @@ -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 platform to retrieve (cloud, oss, v1compat, all). +# Specify a context 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 -# sh ./getswagger.sh -b -# sh ./getswagger.sh -c -o -b +# sh ./getswagger.sh +# sh ./getswagger.sh -b +# sh ./getswagger.sh -c -o -b # # Examples: # sh ./getswagger.sh cloud @@ -33,15 +33,13 @@ baseUrl="https://raw.githubusercontent.com/influxdata/openapi/master" baseUrlOSS="https://raw.githubusercontent.com/influxdata/openapi/docs-release/influxdb-oss" ossVersion=${latestOSS%/} verbose="" -platform="" +context="" function showHelp { - echo "Usage: ./getswagger.sh " + echo "Usage: ./getswagger.sh " echo " With optional arguments:" - echo " ./getswagger.sh -b -V" - echo " ./getswagger.sh cloud" + echo " ./getswagger.sh -b -V" echo " ./getswagger.sh oss -o -V" - echo " ./getswagger.sh all -o " echo "Commands:" echo "-b The base URL to fetch from." echo " ex. ./getswagger.sh -b file:///Users/yourname/github/openapi" @@ -57,7 +55,7 @@ subcommand=$1 case "$subcommand" in cloud|oss|v1compat|all) - platform=$1 + context=$1 shift while getopts ":o:b:hV" opt; do @@ -79,12 +77,10 @@ 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 @@ -93,7 +89,7 @@ case "$subcommand" in esac function showArgs { - echo "platform: $platform"; + echo "context: $context"; echo "baseUrl: $baseUrl"; echo "ossVersion: $ossVersion"; } @@ -120,52 +116,44 @@ function postProcess() { } function updateCloud { - outFile="cloud/ref.yml" - curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile - postProcess $outFile cloud + curl ${verbose} ${baseUrl}/contracts/ref/cloud.yml -s -o cloud/ref.yml + postProcess $_ cloud } function updateOSS { - mkdir -p ${ossVersion} - outFile="$ossVersion/ref.yml" - curl $UPDATE_OPTIONS ${baseUrlOSS}/contracts/ref/oss.yml -o $outFile - postProcess $outFile $ossVersion + mkdir -p ${ossVersion} && curl ${verbose} ${baseUrlOSS}/contracts/ref/oss.yml -s -o $_/ref.yml + postProcess $_ $ossVersion } function updateV1Compat { - outFile="cloud/swaggerV1Compat.yml" - curl $UPDATE_OPTIONS ${baseUrl}/contracts/swaggerV1Compat.yml -o $outFile - postProcess $outFile cloud v1compat + curl ${verbose} ${baseUrl}/contracts/swaggerV1Compat.yml -s -o cloud/swaggerV1Compat.yml + postProcess $_ cloud v1compat - outFile="$ossVersion/swaggerV1Compat.yml" - mkdir -p ${ossVersion} && cp cloud/swaggerV1Compat.yml $outFile - postProcess $outFile $ossVersion v1compat + mkdir -p ${ossVersion} && cp cloud/swaggerV1Compat.yml $_/swaggerV1Compat.yml + postProcess $_ $ossVersion v1compat } -UPDATE_OPTIONS="--fail" - if [ ! -z ${verbose} ]; then - UPDATE_OPTIONS="-v $UPDATE_OPTIONS" showArgs echo "" fi -if [ "$platform" = "cloud" ]; +if [ "$context" = "cloud" ]; then updateCloud -elif [ "$platform" = "oss" ]; +elif [ "$context" = "oss" ]; then updateOSS -elif [ "$platform" = "v1compat" ]; +elif [ "$context" = "v1compat" ]; then updateV1Compat -elif [ "$platform" = "all" ]; +elif [ "$context" = "all" ]; then updateCloud updateOSS updateV1Compat else - echo "Provide a platform argument: cloud, oss, v1compat, or all." + echo "Provide a context (cloud, oss, v1compat, all)" showHelp fi