From abc789013f5fa4572b912a1cf922f9b15ee3a22a Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 10 Mar 2026 14:24:49 -0500 Subject: [PATCH] refactor(api-docs): flatten version subdirectories for v2-compat and v1 products MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop redundant version subdirectories and use self-documenting filenames for 5 products: v2-compat influxdb3: cloud-dedicated/v2/ref.yml → cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml cloud-serverless/v2/ref.yml → cloud-serverless/influxdb3-cloud-serverless-openapi.yaml clustered/v2/ref.yml → clustered/influxdb3-clustered-openapi.yaml v1: influxdb/v1/v1/ref.yml → influxdb/v1/influxdb-oss-v1-openapi.yaml enterprise_influxdb/v1/v1/ref.yml → enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml Update .config.yml, getswagger.sh, and generate-openapi-articles.ts to reference new paths. --- api-docs/enterprise_influxdb/v1/.config.yml | 2 +- api-docs/getswagger.sh | 16 +++++++------- api-docs/influxdb/v1/.config.yml | 2 +- .../influxdb3/cloud-dedicated/.config.yml | 4 ++-- .../influxdb3/cloud-serverless/.config.yml | 4 ++-- api-docs/influxdb3/clustered/.config.yml | 4 ++-- api-docs/scripts/README.md | 10 ++++----- api-docs/scripts/generate-openapi-articles.ts | 22 +++++++++---------- 8 files changed, 32 insertions(+), 32 deletions(-) diff --git a/api-docs/enterprise_influxdb/v1/.config.yml b/api-docs/enterprise_influxdb/v1/.config.yml index 021084937..88da17b3f 100644 --- a/api-docs/enterprise_influxdb/v1/.config.yml +++ b/api-docs/enterprise_influxdb/v1/.config.yml @@ -7,4 +7,4 @@ x-influxdata-product-name: InfluxDB Enterprise v1 apis: v1@1: - root: v1/ref.yml + root: influxdb-enterprise-v1-openapi.yaml diff --git a/api-docs/getswagger.sh b/api-docs/getswagger.sh index 4af89f4e9..aa2aa15ad 100755 --- a/api-docs/getswagger.sh +++ b/api-docs/getswagger.sh @@ -166,25 +166,25 @@ function updateCloudDedicatedManagement { } function updateCloudDedicatedV2 { - outFile="influxdb3/cloud-dedicated/v2/ref.yml" + outFile="influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml" if [[ -z "$baseUrl" ]]; then echo "Using existing $outFile" else curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile fi - postProcess $outFile 'influxdb3/cloud-dedicated/.config.yml' v2@2 + postProcess $outFile 'influxdb3/cloud-dedicated/.config.yml' data@2 } function updateCloudServerlessV2 { - outFile="influxdb3/cloud-serverless/v2/ref.yml" + outFile="influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml" if [[ -z "$baseUrl" ]]; then echo "Using existing $outFile" else curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile fi - postProcess $outFile 'influxdb3/cloud-serverless/.config.yml' v2@2 + postProcess $outFile 'influxdb3/cloud-serverless/.config.yml' data@2 } function updateClusteredManagement { @@ -204,14 +204,14 @@ function updateClusteredManagement { } function updateClusteredV2 { - outFile="influxdb3/clustered/v2/ref.yml" + outFile="influxdb3/clustered/influxdb3-clustered-openapi.yaml" if [[ -z "$baseUrl" ]]; then echo "Using existing $outFile" else curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile fi - postProcess $outFile 'influxdb3/clustered/.config.yml' v2@2 + postProcess $outFile 'influxdb3/clustered/.config.yml' data@2 } function updateCoreV3 { @@ -274,13 +274,13 @@ function updateV1Compat { } function updateOSSV1 { - outFile="influxdb/v1/v1/ref.yml" + outFile="influxdb/v1/influxdb-oss-v1-openapi.yaml" echo "Processing $outFile with decorators" postProcess $outFile 'influxdb/v1/.config.yml' 'v1@1' } function updateEnterpriseV1 { - outFile="enterprise_influxdb/v1/v1/ref.yml" + outFile="enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml" echo "Processing $outFile with decorators" postProcess $outFile 'enterprise_influxdb/v1/.config.yml' 'v1@1' } diff --git a/api-docs/influxdb/v1/.config.yml b/api-docs/influxdb/v1/.config.yml index 0d8af024f..b89f41a85 100644 --- a/api-docs/influxdb/v1/.config.yml +++ b/api-docs/influxdb/v1/.config.yml @@ -7,4 +7,4 @@ x-influxdata-product-name: InfluxDB OSS v1 apis: v1@1: - root: v1/ref.yml + root: influxdb-oss-v1-openapi.yaml diff --git a/api-docs/influxdb3/cloud-dedicated/.config.yml b/api-docs/influxdb3/cloud-dedicated/.config.yml index f784adf26..12a9450ba 100644 --- a/api-docs/influxdb3/cloud-dedicated/.config.yml +++ b/api-docs/influxdb3/cloud-dedicated/.config.yml @@ -6,8 +6,8 @@ extends: x-influxdata-product-name: InfluxDB 3 Cloud Dedicated apis: - v2@2: - root: v2/ref.yml + data@2: + root: influxdb3-cloud-dedicated-openapi.yaml x-influxdata-docs-aliases: - /influxdb3/cloud-dedicated/api/ - /influxdb3/cloud-dedicated/api/v1/ diff --git a/api-docs/influxdb3/cloud-serverless/.config.yml b/api-docs/influxdb3/cloud-serverless/.config.yml index e845948d0..e1a9421b5 100644 --- a/api-docs/influxdb3/cloud-serverless/.config.yml +++ b/api-docs/influxdb3/cloud-serverless/.config.yml @@ -6,8 +6,8 @@ extends: x-influxdata-product-name: InfluxDB 3 Serverless apis: - v2@2: - root: v2/ref.yml + data@2: + root: influxdb3-cloud-serverless-openapi.yaml x-influxdata-docs-aliases: - /influxdb3/cloud-serverless/api/ v1-compatibility@2: diff --git a/api-docs/influxdb3/clustered/.config.yml b/api-docs/influxdb3/clustered/.config.yml index 4fe722f84..5d6205910 100644 --- a/api-docs/influxdb3/clustered/.config.yml +++ b/api-docs/influxdb3/clustered/.config.yml @@ -6,8 +6,8 @@ extends: x-influxdata-product-name: InfluxDB 3 Clustered apis: - v2@2: - root: v2/ref.yml + data@2: + root: influxdb3-clustered-openapi.yaml x-influxdata-docs-aliases: - /influxdb3/clustered/api/ - /influxdb3/clustered/api/v1/ diff --git a/api-docs/scripts/README.md b/api-docs/scripts/README.md index 2ea5f440d..96d864397 100644 --- a/api-docs/scripts/README.md +++ b/api-docs/scripts/README.md @@ -57,11 +57,11 @@ yarn build:api-pages:product cloud-v2 oss-v2 | ---------------------- | ------------------------- | ------------------------------------------------ | -------------------------------------------- | | `cloud-v2` | InfluxDB Cloud (v2 API) | `api-docs/cloud/v2/ref.yml` | `content/influxdb/cloud/api/v2` | | `oss-v2` | InfluxDB OSS v2 | `api-docs/v2/ref.yml` | `content/influxdb/v2/api/v2` | -| `influxdb3-core` | InfluxDB 3 Core | `api-docs/influxdb3/core/v3/ref.yml` | `content/influxdb3/core/reference/api` | -| `influxdb3-enterprise` | InfluxDB 3 Enterprise | `api-docs/influxdb3/enterprise/v3/ref.yml` | `content/influxdb3/enterprise/reference/api` | -| `cloud-dedicated` | InfluxDB Cloud Dedicated | `api-docs/influxdb3/cloud-dedicated/v2/ref.yml` | `content/influxdb/cloud-dedicated/api` | -| `cloud-serverless` | InfluxDB Cloud Serverless | `api-docs/influxdb3/cloud-serverless/v2/ref.yml` | `content/influxdb/cloud-serverless/api` | -| `clustered` | InfluxDB Clustered | `api-docs/influxdb3/clustered/v2/ref.yml` | `content/influxdb/clustered/api` | +| `influxdb3-core` | InfluxDB 3 Core | `api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml` | `content/influxdb3/core/reference/api` | +| `influxdb3-enterprise` | InfluxDB 3 Enterprise | `api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml` | `content/influxdb3/enterprise/reference/api` | +| `cloud-dedicated` | InfluxDB Cloud Dedicated | `api-docs/influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml` | `content/influxdb/cloud-dedicated/api` | +| `cloud-serverless` | InfluxDB Cloud Serverless | `api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml` | `content/influxdb/cloud-serverless/api` | +| `clustered` | InfluxDB Clustered | `api-docs/influxdb3/clustered/influxdb3-clustered-openapi.yaml` | `content/influxdb/clustered/api` | ## Architecture diff --git a/api-docs/scripts/generate-openapi-articles.ts b/api-docs/scripts/generate-openapi-articles.ts index 8ecf7cb00..43257124c 100644 --- a/api-docs/scripts/generate-openapi-articles.ts +++ b/api-docs/scripts/generate-openapi-articles.ts @@ -935,14 +935,14 @@ const productConfigs: ProductConfigMap = { // InfluxDB 3 products use tag-based generation for better UX // Keys use underscores to match Hugo data directory structure influxdb3_core: { - specFile: path.join(API_DOCS_ROOT, 'influxdb3/core/v3/ref.yml'), + specFile: path.join(API_DOCS_ROOT, 'influxdb3/core/v3/influxdb3-core-openapi.yaml'), pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/core'), description: 'InfluxDB 3 Core', menuKey: 'influxdb3_core', useTagBasedGeneration: true, }, influxdb3_enterprise: { - specFile: path.join(API_DOCS_ROOT, 'influxdb3/enterprise/v3/ref.yml'), + specFile: path.join(API_DOCS_ROOT, 'influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml'), pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/enterprise'), description: 'InfluxDB 3 Enterprise', menuKey: 'influxdb3_enterprise', @@ -965,7 +965,7 @@ const productConfigs: ProductConfigMap = { displayName: 'Management API', }, { - path: path.join(API_DOCS_ROOT, 'influxdb3/cloud-dedicated/v2/ref.yml'), + path: path.join(API_DOCS_ROOT, 'influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml'), displayName: 'v2 Data API', }, ], @@ -976,7 +976,7 @@ const productConfigs: ProductConfigMap = { useTagBasedGeneration: true, }, 'cloud-serverless': { - specFile: path.join(API_DOCS_ROOT, 'influxdb3/cloud-serverless/v2/ref.yml'), + specFile: path.join(API_DOCS_ROOT, 'influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml'), pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/cloud-serverless'), description: 'InfluxDB Cloud Serverless', menuKey: 'influxdb3_cloud_serverless', @@ -993,7 +993,7 @@ const productConfigs: ProductConfigMap = { displayName: 'Management API', }, { - path: path.join(API_DOCS_ROOT, 'influxdb3/clustered/v2/ref.yml'), + path: path.join(API_DOCS_ROOT, 'influxdb3/clustered/influxdb3-clustered-openapi.yaml'), displayName: 'v2 Data API', }, ], @@ -1007,7 +1007,7 @@ const productConfigs: ProductConfigMap = { // These have existing /tools/api/ pages with menu entries, // so we skip adding menu entries to the generated parent pages. 'oss-v1': { - specFile: path.join(API_DOCS_ROOT, 'influxdb/v1/v1/ref.yml'), + specFile: path.join(API_DOCS_ROOT, 'influxdb/v1/influxdb-oss-v1-openapi.yaml'), pagesDir: path.join(DOCS_ROOT, 'content/influxdb/v1'), description: 'InfluxDB OSS v1', menuKey: 'influxdb_v1', @@ -1015,7 +1015,7 @@ const productConfigs: ProductConfigMap = { useTagBasedGeneration: true, }, 'enterprise-v1': { - specFile: path.join(API_DOCS_ROOT, 'enterprise_influxdb/v1/v1/ref.yml'), + specFile: path.join(API_DOCS_ROOT, 'enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml'), pagesDir: path.join(DOCS_ROOT, 'content/enterprise_influxdb/v1'), description: 'InfluxDB Enterprise v1', menuKey: 'enterprise_influxdb_v1', @@ -1034,11 +1034,11 @@ const LINK_PATTERN = /\/influxdb\/version\//g; * Derive documentation root from spec file path. * * @example - * 'api-docs/influxdb3/core/v3/ref.yml' → '/influxdb3/core' - * 'api-docs/influxdb3/enterprise/v3/ref.yml' → '/influxdb3/enterprise' + * 'api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml' → '/influxdb3/core' + * 'api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml' → '/influxdb3/enterprise' * 'api-docs/influxdb/v2/v2/ref.yml' → '/influxdb/v2' - * 'api-docs/influxdb/v1/v1/ref.yml' → '/influxdb/v1' - * 'api-docs/enterprise_influxdb/v1/v1/ref.yml' → '/enterprise_influxdb/v1' + * 'api-docs/influxdb/v1/influxdb-oss-v1-openapi.yaml' → '/influxdb/v1' + * 'api-docs/enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml' → '/enterprise_influxdb/v1' */ function deriveProductPath(specPath: string): string { // Match: api-docs/(enterprise_influxdb|influxdb3|influxdb)/(product-or-version)/...