From 4194ef5eb97ccc412bfbad09a47e9435e24b9296 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 26 Feb 2025 16:07:28 -0600 Subject: [PATCH] fix(api): Add shortDescription to replace summary - Add a custom x-influxdata-short-description field that replaces the previous non-standard summary field used by Redocly. - Double quote the title and description vars to preserve the entire value when passing them to the CLI --- api-docs/generate-api-docs.sh | 12 +++++------- .../influxdb/cloud/v1-compatibility/content/info.yml | 1 + api-docs/influxdb/cloud/v2/content/info.yml | 1 + .../v1-compatibility/content/info.yml | 1 + .../influxdb3/cloud-dedicated/v2/content/info.yml | 1 + .../v1-compatibility/content/info.yml | 1 + .../influxdb3/cloud-serverless/v2/content/info.yml | 1 + .../clustered/v1-compatibility/content/info.yml | 1 + api-docs/influxdb3/clustered/v2/content/info.yml | 1 + api-docs/influxdb3/core/v3/content/info.yml | 1 + api-docs/influxdb3/enterprise/v3/content/info.yml | 1 + 11 files changed, 15 insertions(+), 7 deletions(-) diff --git a/api-docs/generate-api-docs.sh b/api-docs/generate-api-docs.sh index 0f8b89ca3..1e7820a7e 100755 --- a/api-docs/generate-api-docs.sh +++ b/api-docs/generate-api-docs.sh @@ -54,10 +54,8 @@ 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) - # 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 | tr '\n' '\r' | sed 's/\r/\\n/g' | sed 's/"/\\"/g') + # Get the shortened description to use for metadata. + local shortDescription=$(yq '.x-influxdata-short-description' $productVersion/$apiName/content/info.yml) # 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. @@ -82,20 +80,20 @@ function generateHtml { npm_config_yes=true npx redoc-cli@0.12.3 bundle $specPath \ --config $configPath \ -t template.hbs \ - --title=$title \ + --title="$title" \ --options.sortPropsAlphabetically \ --options.menuToggle \ --options.hideDownloadButton \ --options.hideHostname \ --options.noAutoAuth \ --output=$specbundle \ - --templateOptions.description= $(echo "$description" | sed 's/\n//g') \ + --templateOptions.description="$shortDescription" \ --templateOptions.product="$productVersion" \ --templateOptions.productName="$productName" local frontmatter=$(yq eval -n \ ".title = \"$title\" | - .description = \"$description\" | + .description = \"$shortDescription\" | .layout = \"api\" | .weight = $weight | .menu.[\"$menu\"].parent = \"InfluxDB HTTP API\" | diff --git a/api-docs/influxdb/cloud/v1-compatibility/content/info.yml b/api-docs/influxdb/cloud/v1-compatibility/content/info.yml index 60e607a79..b6a8e2171 100644 --- a/api-docs/influxdb/cloud/v1-compatibility/content/info.yml +++ b/api-docs/influxdb/cloud/v1-compatibility/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB v1 HTTP API for InfluxDB Cloud (TSM) x-influxdata-short-title: v1 Compatibility API +x-influxdata-short-description: The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB v2 bucket using InfluxDB v1 endpoints. description: | The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB v2 bucket using InfluxDB v1 endpoints. diff --git a/api-docs/influxdb/cloud/v2/content/info.yml b/api-docs/influxdb/cloud/v2/content/info.yml index ff0de618c..b8f780933 100644 --- a/api-docs/influxdb/cloud/v2/content/info.yml +++ b/api-docs/influxdb/cloud/v2/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB Cloud API Service x-influxdata-short-title: v2 API +x-influxdata-short-description: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with InfluxDB v2. description: | The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with InfluxDB v2. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints. diff --git a/api-docs/influxdb3/cloud-dedicated/v1-compatibility/content/info.yml b/api-docs/influxdb3/cloud-dedicated/v1-compatibility/content/info.yml index f5781b37b..01296adc6 100644 --- a/api-docs/influxdb3/cloud-dedicated/v1-compatibility/content/info.yml +++ b/api-docs/influxdb3/cloud-dedicated/v1-compatibility/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Dedicated x-influxdata-short-title: v1 Compatibility API +x-influxdata-short-description: The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB 3 Cloud Dedicated database using InfluxDB v1 endpoints. description: | The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB 3 Cloud Dedicated database using InfluxDB v1 endpoints. diff --git a/api-docs/influxdb3/cloud-dedicated/v2/content/info.yml b/api-docs/influxdb3/cloud-dedicated/v2/content/info.yml index 4fd037931..ec3537315 100644 --- a/api-docs/influxdb3/cloud-dedicated/v2/content/info.yml +++ b/api-docs/influxdb3/cloud-dedicated/v2/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB v2 HTTP API for InfluxDB 3 Cloud Dedicated x-influxdata-short-title: v2 API +x-influxdata-short-description: The InfluxDB v2 HTTP API provides a v2-compatible programmatic interface for writing and managing data stored in an InfluxDB 3 Cloud Dedicated database. description: | The InfluxDB v2 HTTP API provides a v2-compatible programmatic interface for writing and managing data stored in an InfluxDB 3 Cloud Dedicated database. diff --git a/api-docs/influxdb3/cloud-serverless/v1-compatibility/content/info.yml b/api-docs/influxdb3/cloud-serverless/v1-compatibility/content/info.yml index e565e78f4..ceb3cd409 100644 --- a/api-docs/influxdb3/cloud-serverless/v1-compatibility/content/info.yml +++ b/api-docs/influxdb3/cloud-serverless/v1-compatibility/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Serverless x-influxdata-short-title: v1 Compatibility API +x-influxdata-short-description: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket. description: | The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket. diff --git a/api-docs/influxdb3/cloud-serverless/v2/content/info.yml b/api-docs/influxdb3/cloud-serverless/v2/content/info.yml index 182d11894..4a23ed31d 100644 --- a/api-docs/influxdb3/cloud-serverless/v2/content/info.yml +++ b/api-docs/influxdb3/cloud-serverless/v2/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB 3 Cloud Serverless API Service x-influxdata-short-title: v2 API +x-influxdata-short-description: The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket. description: | The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket. diff --git a/api-docs/influxdb3/clustered/v1-compatibility/content/info.yml b/api-docs/influxdb3/clustered/v1-compatibility/content/info.yml index ba251c29a..8c7102361 100644 --- a/api-docs/influxdb3/clustered/v1-compatibility/content/info.yml +++ b/api-docs/influxdb3/clustered/v1-compatibility/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered x-influxdata-short-title: v1 Compatibility API +x-influxdata-short-description: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database. description: | The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database. diff --git a/api-docs/influxdb3/clustered/v2/content/info.yml b/api-docs/influxdb3/clustered/v2/content/info.yml index f2fedfd0f..cbd9281e2 100644 --- a/api-docs/influxdb3/clustered/v2/content/info.yml +++ b/api-docs/influxdb3/clustered/v2/content/info.yml @@ -1,5 +1,6 @@ title: InfluxDB 3 Clustered API Service x-influxdata-short-title: v2 API +x-influxdata-short-description: The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database. description: | The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database. diff --git a/api-docs/influxdb3/core/v3/content/info.yml b/api-docs/influxdb3/core/v3/content/info.yml index d5052ecf6..0e8504b28 100644 --- a/api-docs/influxdb3/core/v3/content/info.yml +++ b/api-docs/influxdb3/core/v3/content/info.yml @@ -4,6 +4,7 @@ x-influxdata-version-matrix: v1: Compatibility layer for InfluxDB 1.x clients (supported) v2: Compatibility layer for InfluxDB 2.x clients (supported) v3: Native API for InfluxDB 3.x (current) +x-influxdata-short-description: The InfluxDB 3 HTTP API provides a programmatic interface for interactions with InfluxDB, including writing, querying, and processing data, and managing an InfluxDB 3 instance. description: | The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for interacting with InfluxDB 3 Core databases and resources. diff --git a/api-docs/influxdb3/enterprise/v3/content/info.yml b/api-docs/influxdb3/enterprise/v3/content/info.yml index e87e531a0..6587191d7 100644 --- a/api-docs/influxdb3/enterprise/v3/content/info.yml +++ b/api-docs/influxdb3/enterprise/v3/content/info.yml @@ -4,6 +4,7 @@ x-influxdata-version-matrix: v1: Compatibility layer for InfluxDB 1.x clients (supported) v2: Compatibility layer for InfluxDB 2.x clients (supported) v3: Native API for InfluxDB 3.x (current) +x-influxdata-short-description: The InfluxDB 3 HTTP API provides a programmatic interface for interactions with InfluxDB, including writing, querying, and processing data, and managing an InfluxDB 3 instance. description: | The InfluxDB HTTP API for InfluxDB 3 Enterprise provides a programmatic interface for interacting with InfluxDB 3 Enterprise databases and resources.