feat(api): implement shared OpenAPI schemas for Core and Enterprise

.gitignore

@@ -12,8 +12,20 @@ package-lock.json
 
 # Content generation
 /content/influxdb*/**/api/**/*.html
+/content/influxdb*/**/api/**/*.md
 !api-docs/**/.config.yml
 /api-docs/redoc-static.html*
+
+# API documentation generation (generated by api-docs/scripts/)
+/content/influxdb/*/api/**
+/content/influxdb3/*/api/**
+/content/influxdb3/*/reference/api/**
+/static/openapi
+
+# Exception: hand-crafted API conceptual pages (not generated)
+!/content/influxdb3/*/api/administration/
+!/content/influxdb3/*/api/administration/_index.md
+
 /helper-scripts/output/*
 /telegraf-build
 !telegraf-build/templates
@@ -38,6 +50,8 @@ tmp
 
 # TypeScript build output
 **/dist/
+# Exception: include compiled API doc scripts for easier use
+!api-docs/scripts/dist/
 **/dist-lambda/
 
 # User context files for AI assistant tools

api-docs/README.md

@@ -48,6 +48,7 @@
    ```
 
 3. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
+
 4. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
 
 ## Update API docs for an InfluxDB OSS release
@@ -106,8 +107,8 @@
    # Copy the old version directory to a directory for the new version:
    cp -r v2.2 v2.3
    ```
-   
-8. In your editor, update custom content files in NEW_VERSION/content.
+
+8. In your editor, update custom content files in NEW\_VERSION/content.
 
 9. Enter the following commands into your terminal to fetch and process the contracts:
 
@@ -117,6 +118,7 @@
    ```
 
 10. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
+
 11. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
 
 ## Update API docs for OSS spec changes between releases
@@ -142,6 +144,8 @@ Follow these steps to update OSS API docs between version releases--for example,
    git cherry-pick [COMMIT_SHAs]
    git push -f origin docs-release/influxdb-oss
 
+   ```
+
 4. Go into your `docs-v2` directory and create a branch for your changes--for example:
 
    ```sh
@@ -165,6 +169,7 @@ Follow these steps to update OSS API docs between version releases--for example,
    ```
 
 7. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
+
 8. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
 
 ## Generate InfluxDB API docs
@@ -197,7 +202,7 @@ The script uses `npx` to download and execute the Redocly CLI.
 
    If `npx` returns errors, [download](https://nodejs.org/en/) and run a recent version of the Node.js installer for your OS.
 
-2. To generate API docs for _all_ InfluxDB versions in `./openapi`, enter the following command into your terminal:
+2. To generate API docs for *all* InfluxDB versions in `./openapi`, enter the following command into your terminal:
 
    ```sh
    sh generate-api-docs.sh
@@ -239,17 +244,17 @@ We regenerate API reference docs from `influxdata/openapi`
 
 ### InfluxDB OSS v2 version
 
- Given that
- `influxdata/openapi` **master** may contain OSS spec changes not implemented
- in the current OSS release, we (Docs team) maintain a release branch, `influxdata/openapi`
+Given that
+`influxdata/openapi` **master** may contain OSS spec changes not implemented
+in the current OSS release, we (Docs team) maintain a release branch, `influxdata/openapi`
 **docs-release/influxdb-oss**, used to generate OSS reference docs.
 
 ### How to find the API spec used by an InfluxDB OSS version
 
 `influxdata/openapi` does not version the InfluxData API.
 To find the `influxdata/openapi` commit SHA used in a specific version of InfluxDB OSS,
 see `/scripts/fetch-swagger.sh` in `influxdata/influxdb`--for example,
-for the `influxdata/openapi` commit used in OSS v2.2.0, see https://github.com/influxdata/influxdb/blob/v2.2.0/scripts/fetch-swagger.sh#L13=.
+for the `influxdata/openapi` commit used in OSS v2.2.0, see <https://github.com/influxdata/influxdb/blob/v2.2.0/scripts/fetch-swagger.sh#L13=>.
 For convenience, we tag `influxdata/influxdb` (OSS) release points in `influxdata/openapi` as
 `influxdb-oss-v[OSS_VERSION]`. See <https://github.com/influxdata/openapi/tags>.
 
@@ -281,16 +286,17 @@ To add new YAML files for other nodes in the contracts, follow these steps:
 
 `@redocly/cli` also provides some [built-in decorators](https://redocly.com/docs/cli/decorators/)
 that you can configure in `.redocly` without having to write JavaScript.
+
 ### How to add tag content or describe a group of paths
 
 In API reference docs, we use OpenAPI `tags` elements for navigation,
 the `x-traitTag` vendor extension for providing custom content, and the `x-tagGroups` vendor extension
 for grouping tags in navigation.
 
-| Example                                                                                                | OpenAPI field                                         |                                            |
-|:-------------------------------------------------------------------------------------------------------|-------------------------------------------------------|--------------------------------------------|
-| [Add supplementary documentation](https://docs.influxdata.com/influxdb/cloud/api/#tag/Quick-start)     | `tags: [ { name: 'Quick start', x-traitTag: true } ]` | [Source](https://github.com/influxdata/openapi/master/src/cloud/tags.yml) |
-| Group tags in navigation                                                                               | `x-tagGroups: [ { name: 'All endpoints', tags: [...], ...} ]`   | [Source](https://github.com/influxdata/docs-v2/blob/da6c2e467de7212fc2197dfe0b87f0f0296688ee/api-docs/cloud-iox/content/tag-groups.yml)) |
+| Example                                                                                            | OpenAPI field                                                 |                                                                                                                                          |
+| :------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| [Add supplementary documentation](https://docs.influxdata.com/influxdb/cloud/api/#tag/Quick-start) | `tags: [ { name: 'Quick start', x-traitTag: true } ]`         | [Source](https://github.com/influxdata/openapi/master/src/cloud/tags.yml)                                                                |
+| Group tags in navigation                                                                           | `x-tagGroups: [ { name: 'All endpoints', tags: [...], ...} ]` | [Source](https://github.com/influxdata/docs-v2/blob/da6c2e467de7212fc2197dfe0b87f0f0296688ee/api-docs/cloud-iox/content/tag-groups.yml)) |
 
 #### Add and update x-tagGroups
 
@@ -302,6 +308,47 @@ those tags.
 If you assign an empty array(`[]`) to the `All endpoints` x-tagGroup in `PLATFORM/content/tag-groups.yml`,
 the decorator replaces the empty array with the list of tags from all Operations in the spec.
 
+## Documentation links in OpenAPI specs
+
+Use the `/influxdb/version/` placeholder when including InfluxDB links in OpenAPI spec description and summary fields.
+The build process automatically transforms these placeholders to product-specific paths based on the spec file location.
+
+### Writing links
+
+```yaml
+# In api-docs/influxdb3/core/openapi/ref.yml
+info:
+  description: |
+    See [authentication](/influxdb/version/api/authentication/) for details.
+    Related: [tokens](/influxdb/version/admin/tokens/)
+```
+
+After build, these become:
+
+- `/influxdb3/core/api/authentication/`
+- `/influxdb3/core/admin/tokens/`
+
+### How it works
+
+The product path is derived from the spec file location:
+
+- `api-docs/influxdb3/core/...` → `/influxdb3/core`
+- `api-docs/influxdb3/enterprise/...` → `/influxdb3/enterprise`
+- `api-docs/influxdb/v2/...` → `/influxdb/v2`
+
+Only `description` and `summary` fields are transformed.
+Explicit cross-product links (e.g., `/telegraf/v1/plugins/`) remain unchanged.
+
+### Link validation
+
+Run with the `--validate-links` flag to check for broken links:
+
+```bash
+yarn build:api-docs --validate-links
+```
+
+This validates that transformed links point to existing Hugo content files and warns about any broken links.
+
 ## How to test your spec or API reference changes
 
 You can use `getswagger.sh` to fetch contracts from any URL.

api-docs/getswagger.sh

@@ -62,8 +62,13 @@ function showHelp {
 subcommand=$1
 
 case "$subcommand" in
-  cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-management|clustered-v2|cloud-v2|v2|v1-compat|core-v3|enterprise-v3|all)
+  cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-management|clustered-v2|cloud-v2|v2|v1-compat|core-v3|enterprise-v3|influxdb3_core|influxdb3_enterprise|all)
     product=$1
+    # Map alternative product names to canonical names
+    case "$product" in
+      influxdb3_core) product="core-v3" ;;
+      influxdb3_enterprise) product="enterprise-v3" ;;
+    esac
     shift
 
   while getopts ":o:b:BhV" opt; do
@@ -150,19 +155,7 @@ function postProcess() {
 }
 
 function updateCloudDedicatedManagement {
-  outFile="influxdb3/cloud-dedicated/management/openapi.yml"
-  if [[ -z "$baseUrl" ]];
-  then
-    echo "Using existing $outFile"
-  else
-    # Clone influxdata/granite and fetch the latest openapi.yaml file.
-    echo "Fetching the latest openapi.yaml file from influxdata/granite"
-    tmp_dir=$(mktemp -d)
-    git clone --depth 1 --branch main https://github.com/influxdata/granite.git "$tmp_dir"
-    cp "$tmp_dir/openapi.yaml" "$outFile"
-    rm -rf "$tmp_dir"
-  fi
-  postProcess $outFile 'influxdb3/cloud-dedicated/.config.yml' management@0
+  bundleManagementWithOverlay "cloud-dedicated"
 }
 
 function updateCloudDedicatedV2 {
@@ -188,19 +181,7 @@ function updateCloudServerlessV2 {
 }
 
 function updateClusteredManagement {
-  outFile="influxdb3/clustered/management/openapi.yml"
-  if [[ -z "$baseUrl" ]];
-  then
-    echo "Using existing $outFile"
-  else
-    # Clone influxdata/granite and fetch the latest openapi.yaml file.
-    echo "Fetching the latest openapi.yaml file from influxdata/granite"
-    tmp_dir=$(mktemp -d)
-    git clone --depth 1 --branch main https://github.com/influxdata/granite.git "$tmp_dir"
-    cp "$tmp_dir/openapi.yaml" "$outFile"
-    rm -rf "$tmp_dir"
-  fi
-  postProcess $outFile 'influxdb3/clustered/.config.yml' management@0
+  bundleManagementWithOverlay "clustered"
 }
 
 function updateClusteredV2 {
@@ -214,28 +195,59 @@ function updateClusteredV2 {
  postProcess $outFile 'influxdb3/clustered/.config.yml' v2@2
 }
 
+# Bundle shared base spec with product-specific overlay
+# Usage: bundleWithOverlay <product> <apiVersion>
+# Example: bundleWithOverlay "core" "v3"
+function bundleWithOverlay {
+  local product=$1
+  local apiVersion=$2
+
+  local baseFile="influxdb3/shared/${apiVersion}/base.yml"
+  local overlayFile="influxdb3/${product}/${apiVersion}/overlay.yml"
+  local outFile="influxdb3/${product}/${apiVersion}/ref.yml"
+  local configFile="influxdb3/${product}/.config.yml"
+
+  echo "Bundling ${product} ${apiVersion} with overlay..."
+
+  # Apply overlay to base spec (run from project root for node_modules access)
+  local scriptDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+  local projectRoot=$(dirname "$scriptDir")
+
+  (cd "$projectRoot" && node api-docs/scripts/apply-overlay.js "api-docs/$baseFile" "api-docs/$overlayFile" -o "api-docs/$outFile")
+
+  # Apply Redocly decorators (info, servers, tag-groups from content/)
+  postProcess "$outFile" "$configFile" "${apiVersion}@3"
+}
+
+# Bundle shared management base spec with product-specific overlay
+# Usage: bundleManagementWithOverlay <product>
+# Example: bundleManagementWithOverlay "clustered"
+function bundleManagementWithOverlay {
+  local product=$1
+
+  local baseFile="influxdb3/shared/management/base.yml"
+  local overlayFile="influxdb3/${product}/management/overlay.yml"
+  local outFile="influxdb3/${product}/management/openapi.yml"
+  local configFile="influxdb3/${product}/.config.yml"
+
+  echo "Bundling ${product} management with overlay..."
+
+  # Apply overlay to base spec (run from project root for node_modules access)
+  local scriptDir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+  local projectRoot=$(dirname "$scriptDir")
+
+  (cd "$projectRoot" && node api-docs/scripts/apply-overlay.js "api-docs/$baseFile" "api-docs/$overlayFile" -o "api-docs/$outFile")
+
+  # Apply Redocly decorators
+  postProcess "$outFile" "$configFile" "management@0"
+}
+
 function updateCoreV3 {
-  outFile="influxdb3/core/v3/ref.yml"
-  if [[ -z "$baseUrl" ]];
-  then
-    echo "Using existing $outFile"
-  else
-    local url="${baseUrl}/TO_BE_DECIDED"
-    curl $UPDATE_OPTIONS $url -o $outFile
-  fi
-  postProcess $outFile 'influxdb3/core/.config.yml' v3@3
+  bundleWithOverlay "core" "v3"
 }
 
 function updateEnterpriseV3 {
-  outFile="influxdb3/enterprise/v3/ref.yml"
-  if [[ -z "$baseUrl" ]];
-  then
-    echo "Using existing $outFile"
-  else
-    local url="${baseUrl}/TO_BE_DECIDED"
-    curl $UPDATE_OPTIONS $url -o $outFile
-  fi
-  postProcess $outFile 'influxdb3/enterprise/.config.yml' v3@3
+  bundleWithOverlay "enterprise" "v3"
 }
 
 function updateOSSV2 {

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

@@ -126,7 +126,7 @@ tags:
       | Header                   | Value type            | Description                                |
       |:------------------------ |:--------------------- |:-------------------------------------------|
       | `Accept`                 | string                | The content type that the client can understand. |
-      | `Authorization`          | string                | The authorization scheme and credential. |
+      | `Authorization`          | string                | The [authorization scheme and credential](/influxdb/version/api/authentication/). |
       | `Content-Length`         | integer               | The size of the entity-body, in bytes, sent to the database. |
       | `Content-Type`           | string                | The format of the data in the request body. |
     name: Headers

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

@@ -142,7 +142,7 @@ tags:
       | Header                   | Value type            | Description                                |
       |:------------------------ |:--------------------- |:-------------------------------------------|
       | `Accept`                 | string                | The content type that the client can understand. |
-      | `Authorization`          | string                | The authorization scheme and credential. |
+      | `Authorization`          | string                | The [authorization scheme and credential](/influxdb/version/api/authentication/). |
       | `Content-Length`         | integer               | The size of the entity-body, in bytes, sent to the database. |
       | `Content-Type`           | string                | The format of the data in the request body. |
     name: Headers