feat(api): InfluxDB3 Core API reference, API fixes, and e2e tests

- Adds InfluxDB 3 Core API reference
- Updates scripts
- Removes non-valid info.summary field from specs, replaces with description in metadata
- Simplifies frontmatter generation for HTML template
- Reorg of file structure to mirror the content structure.
- Moves OSS v2 into v2/v2/ref.yml to follow the same pattern as others
- Replaces isDefault API config field with specific aliases.
- Misc. fixes.
- Remove generated HTML files.

Author: jstirnaman

.gitignore

@@ -8,7 +8,7 @@ node_modules
 *.log
 /resources
 .hugo_build.lock
-/content/influxdb*/*/api/**/*.html
+/content/influxdb*/**/api/**/*.html
 /api-docs/redoc-static.html*
 .vscode/*
 .idea

api-docs/generate-api-docs.sh

@@ -41,7 +41,6 @@ function generateHtml {
   local productName="$3"
   local api="$4"
   local configPath="$5"
-  local isDefault=$6
 
   # Use the product name to define the menu for the Hugo template
   local menu="$(echo $productVersion | sed 's/\./_/g;s/-/_/g;s/\//_/g;')"
@@ -55,12 +54,25 @@ function generateHtml {
   # Use the title and summary defined in the product API's info.yml file.
   local title=$(yq '.title' $productVersion/$apiName/content/info.yml)
   local menuTitle=$(yq '.x-influxdata-short-title' $productVersion/$apiName/content/info.yml)
-  local description=$(yq '.summary' $productVersion/$apiName/content/info.yml)
+  # Get the first paragraph of the description for the meta description.
+
+  # Get the description with whitespace and newlines preserved.
+  local description=$(yq e -r '.description // ""' $productVersion/$apiName/content/info.yml | sed ':a;N;$!ba;s/\n/\\n/g' | sed 's/"/\\"/g')
+  # Get the aliases array from the configuration file.
+  local aliases=$(yq e ".apis | .$api | .x-influxdata-docs-aliases" "$configPath")
+  # If aliases is null, set it to an empty YAML array. 
+  if [[ "$aliases" == "null" ]]; then
+    aliases='[]'
+  fi
+  local weight=102
+  if [[ $apiName == "v1-compatibility" ]]; then
+    weight=304
+  fi
   # Define the file name for the Redoc HTML output.
   local specbundle=redoc-static_index.html
   # Define the temporary file for the Hugo template and Redoc HTML.
   local tmpfile="${productVersion}-${api}_index.tmp"
-
+  
   echo "Bundling $specPath"
 
   # Use npx to install and run the specified version of redoc-cli.
@@ -77,68 +89,24 @@ function generateHtml {
   --options.hideHostname \
   --options.noAutoAuth \
   --output=$specbundle \
-  --templateOptions.description=$description \
+  --templateOptions.description= $(echo "$description" | sed 's/\n//g') \
   --templateOptions.product="$productVersion" \
   --templateOptions.productName="$productName"
 
-  if [[ $apiName == "v1-compatibility" ]]; then
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 304
-aliases:
-  - /influxdb/$versionDir/api/v1/
----
-"
-  elif [[ $apiVersion == "0" ]]; then
-  echo $productName $apiName
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-weight: 102
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
+  local frontmatter=$(yq eval -n \
+      ".title = \"$title\" |
+       .description = \"$description\" |
+       .layout = \"api\" |
+       .weight = $weight |
+       .menu.[\"$menu\"].parent = \"InfluxDB HTTP API\" |
+       .menu.[\"$menu\"].name = \"$menuTitle\" |
+       .menu.[\"$menu\"].identifier = \"api-reference-$apiName\" |
+      .aliases = \"$aliases\"")
+
+  frontmatter="---
+$frontmatter
 ---
 "
-  elif [[ $isDefault == true ]]; then
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 102
-aliases:
-  - /influxdb/$versionDir/api/
----
-"
-  else
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 102
----
-"
-  fi
 
   # Create the Hugo template file with the frontmatter and Redoc HTML
   echo "$frontmatter" >> $tmpfile
@@ -199,13 +167,7 @@ function build {
       if [ -d "$specPath" ] || [ ! -f "$specPath" ]; then
         echo "OpenAPI spec $specPath doesn't exist."
       fi
-      # Get default status from the configuration.
-      local isDefault=false
-      local defaultStatus
-      defaultStatus=$(yq e ".apis | .$api | .x-influxdata-default" "$configPath")
-      if [[ $defaultStatus == "true" ]]; then
-        isDefault=true
-      fi
+
 
       # If the spec file differs from master, regenerate the HTML.
       local update=0
@@ -219,9 +181,9 @@ function build {
 
       if [[ $update -eq 0 ]]; then
         echo "Regenerating $version $api"
-        generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath" "$isDefault"
+        generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath"
       fi
-      echo "========Done with $version $api========"
+      echo -e "========Finished $version $api========\n\n"
     done <<< "$apis"
   done
 }

api-docs/getswagger.sh

@@ -223,14 +223,14 @@ function updateEnterpriseV3 {
 }
 
 function updateOSSV2 {
-  outFile="influxdb/v2/ref.yml"
+  outFile="influxdb/v2/v2/ref.yml"
   if [[ -z "$baseUrlOSS" ]];
   then
     echo "Using existing $outFile"
   else
     curl $UPDATE_OPTIONS ${baseUrlOSS}/contracts/ref/oss.yml -o $outFile
   fi
-  postProcess $outFile 'influxdb/v2/.config.yml' '@2'
+  postProcess $outFile 'influxdb/v2/.config.yml' 'v2@2'
 }
 
 function updateV1Compat {

api-docs/influxdb/cloud/.config.yml

@@ -8,6 +8,9 @@ x-influxdata-product-name: InfluxDB v2 Cloud
 apis:
   v2@2:
     root: v2/ref.yml
-    x-influxdata-default: true
+    x-influxdata-docs-aliases:
+      - /influxdb/cloud/api/
   v1-compatibility@2:
     root: v1-compatibility/swaggerV1Compat.yml
+    x-influxdata-docs-aliases:
+      - /influxdb/cloud/api/v1/

api-docs/influxdb/cloud/v2/ref.yml

@@ -12212,7 +12212,7 @@ paths:
             type: string
         - description: |
             A unix timestamp precision.
-            Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) the specified precision
+            Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) with the specified precision
             instead of [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
           in: query
           name: epoch

api-docs/influxdb/v2/.config.yml

@@ -6,8 +6,11 @@ extends:
 x-influxdata-product-name: InfluxDB v2 OSS
 
 apis:
-  '@2':
-    root: ref.yml
-    x-influxdata-default: true
+  v2@2:
+    root: v2/ref.yml
+    x-influxdata-docs-aliases:
+      - /influxdb/v2/api/
   v1-compatibility@2:
     root: v1-compatibility/swaggerV1Compat.yml
+    x-influxdata-docs-aliases:
+      - /influxdb/v2/api/v1/

api-docs/influxdb/v2/content/info.yml

@@ -467,19 +467,3 @@ components:
 
 
         For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
-x-tagGroups:
-  - name: Using the InfluxDB HTTP API
-    tags:
-      - Quick start
-      - Authentication
-      - Supported operations
-      - Headers
-      - Pagination
-      - Response codes
-      - Data I/O endpoints
-      - Security and access endpoints
-      - System information endpoints
-  - name: All endpoints
-    tags:
-      - Query
-      - Write

api-docs/influxdb/v2/v1-compatibility/swaggerV1Compat.yml

@@ -0,0 +1,17 @@
+title: InfluxDB OSS API Service
+x-influxdata-short-title: v2 API
+description: |
+  The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
+
+  The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
+
+  This documentation is generated from the
+  [InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.7.0/contracts/ref/oss.yml).
+version: 2.x
+license:
+  name: MIT
+  url: 'https://opensource.org/licenses/MIT'
+contact:
+  name: InfluxData
+  url: https://www.influxdata.com
+  email: [email protected]