DOC-14186: Public spec for the Sync Gateway REST APIs (#963)

* Remove legacy OpenAPI specs
* Remove unused models
* Move overlays to attachments
* Move bundles to hidden bld directory
* Move overlaid specs to attachments
* Add service-desc attributes
* Update configuration schema template blocks
* Remove adoc yaml parser
* Remove links to client app page
* Move Prometheus metrics source file to partials dir
* Add metrics metadata schema file to attachments
* Move generated HTML partials to REST API module
* Update redocly theme
* Update generate docs script
* Update preview config
* Rebuild output docs — includes 4.0.1 backport

Author: simon-dew

modules/ROOT/generate-docs.sh generate-docs.shmodules/ROOT/generate-docs.sh renamed to generate-docs.sh

@@ -2,8 +2,6 @@
 
 set -exuo pipefail
 
-cd $(dirname "${BASH_SOURCE[0]}")
-
 GIT_ROOT=$(git rev-parse --show-toplevel)
 cd "${GIT_ROOT}"
 
@@ -27,19 +25,17 @@ git reset --hard ${tag}
 cd ..
 
 PATH_TO_SYNC_GATEWAY="${GIT_ROOT}/sync_gateway"
+PATH_TO_REDOCLY="${GIT_ROOT}/redocly"
 
-PATH_TO_BUNDLE="${GIT_ROOT}/modules/ROOT/assets/attachments"
-PATH_TO_OVERLAY="${GIT_ROOT}/modules/ROOT/assets/overlays"
-PATH_TO_TEMP="${GIT_ROOT}/modules/ROOT/assets/bld"
+PATH_TO_ASSETS="${GIT_ROOT}/modules/rest-api/attachments"
+PATH_TO_PARTIALS="${GIT_ROOT}/modules/rest-api/partials"
+PATH_TO_TEMP="${GIT_ROOT}/modules/rest-api/bld"
 PATH_TO_STATIC="${GIT_ROOT}/modules/ROOT/partials/static_restapi"
+PATH_TO_METRICS="${GIT_ROOT}/modules/manage/partials"
 
 # Create a bld directory to hold temporary files, if it doesn't already exist
 [[ -d "${PATH_TO_TEMP}" ]] || mkdir "${PATH_TO_TEMP}"
 
-cat "${PATH_TO_BUNDLE}/metrics_metadata.json"
-jq . "${PATH_TO_BUNDLE}/metrics_metadata.json"
-jq --version
-
 # Use jq to transform the Prometheus metrics file into JSON schema.
 # Temporarily omitting the description until we can sort out Redocly CSS issues.
 # Should be {"type": "integer", "format": .value.type, "description": .value.help}
@@ -48,10 +44,8 @@ npx --yes node-jq 'to_entries |
   map(.value |= del(.added, .labels, .unit, .stability, .help)) |
   from_entries |
   {type: "object", properties: .}' \
-    "${PATH_TO_BUNDLE}/metrics_metadata.json" \
-    > "${PATH_TO_TEMP}/metrics_metadata.json"
-
-cd modules/ROOT
+    "${PATH_TO_METRICS}/metrics_metadata.json" \
+   > "${PATH_TO_ASSETS}/metrics_metadata.json"
 
 generate() {
     WHAT=$1
@@ -61,28 +55,28 @@ generate() {
         --config "${PATH_TO_SYNC_GATEWAY}/.redocly.yaml" \
         "${WHAT}" \
         --dereferenced \
-        --output "${PATH_TO_BUNDLE}/bundled-${WHAT}.yaml"
+        --output "${PATH_TO_TEMP}/${WHAT}.bundle.yaml"
 
     # Get the bundled spec, apply the OpenAPI overlay,
-    # and output to the temporary bld folder.
+    # and output to the attachments folder.
     npx --yes openapi-overlays-js \
-        --openapi "${PATH_TO_BUNDLE}/bundled-${WHAT}.yaml" \
-        --overlay "${PATH_TO_OVERLAY}/${WHAT}.yaml" \
-        > "${PATH_TO_TEMP}/${WHAT}.yaml"
+        --openapi "${PATH_TO_TEMP}/${WHAT}.bundle.yaml" \
+        --overlay "${PATH_TO_ASSETS}/_${WHAT}.overlay.yaml" \
+        > "${PATH_TO_ASSETS}/${WHAT}.overlaid.yaml"
 
     # Build the reference documentation using the overlaid spec.
     npx --yes @redocly/cli \
       build-docs \
-      --config redocly.yaml \
-      "${PATH_TO_TEMP}/${WHAT}.yaml" \
-      --output partials/sgw-openapi-$WHAT.html \
-      --template partials/redocAll.hbs
+      --config "${PATH_TO_REDOCLY}/theme.yaml" \
+      "${PATH_TO_ASSETS}/${WHAT}.overlaid.yaml" \
+      --output "${PATH_TO_PARTIALS}/sgw-openapi-$WHAT.html" \
+      --template "${PATH_TO_PARTIALS}/redocAll.hbs"
 
     # Build the static output using the overlaid spec.
     npx --yes @openapitools/openapi-generator-cli generate \
         --skip-validate-spec \
         --generator-name asciidoc  \
-        --input-spec "${PATH_TO_TEMP}/${WHAT}.yaml" \
+        --input-spec "${PATH_TO_ASSETS}/${WHAT}.overlaid.yaml" \
         --template-dir "${PATH_TO_STATIC}/templates" \
         --additional-properties skipExamples=true \
         --output "${PATH_TO_STATIC}/${WHAT}"