feat(v3): WIP: Revise API specs for Core and Enterprise

- Adds basic support for core and enterprise in getswagger.sh
- Adds custom OpenAPI info for Core and Enterprise
- Validates as OpenAPI 3.0 (using Spectral)
    - operationId
    - tags
- Revises use of Legacy, v2
- TODO: need to check and validate in UI, adjust tags if nec.
- Add and remove components
- Update parameters
- Add examples
- Add tests for Core

Author: jstirnaman

.ci/vale/styles/InfluxDB3-Core/Branding.yml

@@ -0,0 +1,11 @@
+extends: substitution
+message: Did you mean '%s' instead of '%s'
+level: warning
+ignorecase: false 
+# swap maps tokens in form of bad: good
+  # NOTE: The left-hand (bad) side can match the right-hand (good) side;
+  # Vale ignores alerts that match the intended form.
+swap:
+  'cloud-serverless|cloud-dedicated|clustered': core
+  'Cloud Serverless|Cloud Dedicated|Clustered': Core
+  'API token': database token

.ci/vale/styles/InfluxDB3-Core/v3Schema.yml

@@ -0,0 +1,10 @@
+extends: substitution
+message: Did you mean '%s' instead of '%s'
+level: warning
+ignorecase: false 
+# swap maps tokens in form of bad: good
+  # NOTE: The left-hand (bad) side can match the right-hand (good) side;
+  # Vale ignores alerts that match the intended form.
+swap:
+  '(?i)bucket': database
+  '(?i)measurement': table

.frontmatter-schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Title of the page"
+    },
+    "description": {
+      "type": "string",
+      "description": "Page description that supports multi-line text"
+    },
+    "menu": {
+      "type": "object",
+      "properties": {
+        "influxdb3_core": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Menu item name"
+            }
+          },
+          "required": ["name"]
+        }
+      }
+    },
+    "weight": {
+      "type": "integer",
+      "description": "Order weight for menu items",
+      "minimum": 0
+    },
+    "source": {
+      "type": "string",
+      "description": "Path to source content file",
+      "pattern": "^/shared/.+\\.md$"
+    }
+  },
+  "required": ["title", "description", "menu", "weight"]
+}

.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

.vscode/settings.json

@@ -1,4 +1,17 @@
 {
-    "vale.valeCLI.config": " \"${workspaceFolder}/.vale.ini\"",
+    "commentAnchors.tags.anchors": 
+      { "SOURCE": {
+        "scope": "file",
+        "behavior": "link",
+        "iconColor": "#FF0000",
+        "highlightColor": "#FF0000",
+        "style": "bold"
+      }},
+    "commentAnchors.workspace.matchFiles": "**/*.{md,ini,json,yaml,yml}",
+    "commentAnchors.workspace.enabled": true,
+    "yaml.schemas": {
+        "./.frontmatter-schema.json": "${workspaceFolder}/content/**/*.md"
+    },
+    "vale.valeCLI.config": "${workspaceFolder}/.vale.ini",
     "vale.valeCLI.minAlertLevel": "warning",
 }

CONTRIBUTING.md

@@ -46,9 +46,10 @@ To install dependencies listed in package.json:
 4. Install the Yarn package manager and run `yarn` to install project dependencies.
 
 `package.json` contains dependencies for linting and running Git hooks.
+docs-v2 uses [Lefthook](https://github.com/evilmartians/lefthook) to configure and manage pre-commit hooks for linting and testing Markdown content.
+
+Other dependencies used in the project:
 
-- **[husky](https://github.com/typicode/husky)**: manages Git hooks, including the pre-commit hook for linting and testing
-- **[lint-staged](https://github.com/lint-staged/lint-staged)**: passes staged files to commands
 - **[prettier](https://prettier.io/docs/en/)**: formats code, including Markdown, according to style rules for consistency
 
 ### Install Docker
@@ -72,6 +73,17 @@ docker build -t influxdata:docs-pytest -f Dockerfile.pytest .
 
 To run the documentation locally, follow the instructions provided in the README.
 
+### Install Visual Studio Code extensions
+
+If you use Microsoft Visual Studio (VS) Code, you can install extensions
+to help you navigate, check, and edit files.
+
+docs-v2 contains a `./.vscode/settings.json` that configures the following extensions:
+
+- Comment Anchors: recognizes tags (for example, `//SOURCE`) and makes links and filepaths clickable in comments.
+- Vale: shows linter errors and suggestions in the editor.
+- YAML Schemas: validates frontmatter attributes.
+
 ### Make your changes
 
 Make your suggested changes being sure to follow the [style and formatting guidelines](#style--formatting) outline below.
@@ -80,27 +92,25 @@ Make your suggested changes being sure to follow the [style and formatting guide
 
 ### Automatic pre-commit checks
 
-docs-v2 uses Husky to manage Git hook scripts.
-When you try to commit your changes (for example, `git commit`), Git runs
-scripts configured in `.husky/pre-commit`, including linting and tests for your **staged** files.
+docs-v2 uses Lefthook to manage Git hooks, such as pre-commit hooks that lint Markdown and test code blocks.
+When you try to commit changes (`git commit`), Git runs
+the commands configured in `lefthook.yml` which pass your **staged** files to Vale, Prettier, and Pytest (in a Docker container).
 
 ### Skip pre-commit hooks
 
 **We strongly recommend running linting and tests**, but you can skip them
 (and avoid installing dependencies)
-by including the `HUSKY=0` environment variable or the `--no-verify` flag with
+by including the `LEFTHOOK=0` environment variable or the `--no-verify` flag with
 your commit--for example:
 
 ```sh
 git commit -m "<COMMIT_MESSAGE>" --no-verify
 ```
 
 ```sh
-HUSKY=0 git commit
+LEFTHOOK=0 git commit
 ```
 
-For more options, see the [Husky documentation](https://typicode.github.io/husky/how-to.html#skipping-git-hooks).
-
 ### Set up test scripts and credentials
 
 To set up your docs-v2 instance to run tests locally, do the following:

Dockerfile.pytest

@@ -34,6 +34,11 @@ RUN apt-get update && apt-get upgrade -y && apt-get install -y \
   telegraf \
   wget
 
+# Install InfluxDB 3 Core
+RUN curl -O https://www.influxdata.com/d/install_influxdb3.sh \
+&& chmod +x install_influxdb3.sh \
+&& bash -c yes | ./install_influxdb3.sh
+
 RUN ln -s /usr/bin/python3 /usr/bin/python
 
 # Create a virtual environment for Python to avoid conflicts with the system Python and having to use the --break-system-packages flag when installing packages with pip.

api-docs/getswagger.sh

@@ -62,7 +62,7 @@ function showHelp {
 subcommand=$1
 
 case "$subcommand" in
-  cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-v2|cloud-v2|v2|v1-compat|all)
+  cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-v2|cloud-v2|v2|v1-compat|core-v3|enterprise-v3|all)
     product=$1
     shift
 
@@ -176,6 +176,17 @@ function updateCloudDedicatedV2 {
  postProcess $outFile 'influxdb3/cloud-dedicated/.config.yml' v2@2
 }
 
+function updateCloudServerlessV2 {
+  outFile="influxdb3/cloud-serverless/v2/ref.yml"
+  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
+}
+
 function updateClusteredV2 {
   outFile="influxdb3/clustered/v2/ref.yml"
   if [[ -z "$baseUrl" ]];
@@ -187,15 +198,28 @@ function updateClusteredV2 {
  postProcess $outFile 'influxdb3/clustered/.config.yml' v2@2
 }
 
-function updateCloudServerlessV2 {
-  outFile="influxdb3/cloud-serverless/v2/ref.yml"
+function updateCoreV3 {
+  outFile="influxdb3/core/v3/ref.yml"
   if [[ -z "$baseUrl" ]];
   then
     echo "Using existing $outFile"
   else
-    curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile
+    local url="${baseUrl}/TO_BE_DECIDED"
+    curl $UPDATE_OPTIONS $url -o $outFile
   fi
-  postProcess $outFile 'influxdb3/cloud-serverless/.config.yml' v2@2
+  postProcess $outFile 'influxdb3/core/.config.yml' v3@3
+}
+
+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
 }
 
 function updateOSSV2 {
@@ -220,7 +244,7 @@ function updateV1Compat {
   postProcess $outFile 'influxdb/cloud/.config.yml' 'v1-compatibility'
 
   outFile="influxdb/v2/v1-compatibility/swaggerV1Compat.yml"
-  cp cloud/v1-compatibility/swaggerV1Compat.yml $outFile
+  cp influxdb/cloud/v1-compatibility/swaggerV1Compat.yml $outFile
   postProcess $outFile 'influxdb/v2/.config.yml' 'v1-compatibility'
 
   outFile="influxdb3/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml"
@@ -257,6 +281,12 @@ then
 elif [ "$product" = "clustered-v2" ];
 then
   updateClusteredV2
+elif [ "$product" = "core-v3" ];
+then
+  updateCoreV3
+elif [ "$product" = "enterprise-v3" ];
+then
+  updateEnterpriseV3
 elif [ "$product" = "v2" ];
 then
   updateOSSV2
@@ -270,9 +300,11 @@ then
   updateCloudDedicatedManagement
   updateCloudServerlessV2
   updateClusteredV2
+  updateCoreV3
+  updateEnterpriseV3
   updateOSSV2
   updateV1Compat
 else
-  echo "Provide a product argument: cloud-v2, cloud-serverless-v2, cloud-dedicated-v2, clustered-v2, v2, v1-compat, or all."
+  echo "Provide a product argument: cloud-v2, cloud-serverless-v2, cloud-dedicated-v2, cloud-dedicated-management, clustered-v2, core-v3, enterprise-v3, v2, v1-compat, or all."
   showHelp
 fi

api-docs/influxdb3/core/v3/content/info.yml

@@ -0,0 +1,23 @@
+title: InfluxDB 3 Core API Service
+x-influxdata-short-title: InfluxDB 3 API
+x-influxdata-version-matrix:
+  v1: Legacy compatibility layer
+  v2: Backward compatibility with InfluxDB 2.x
+  v3: Current native API
+summary: The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
+description: |
+  Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.
+
+  The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for compatibility with InfluxDB 2.x and InfluxDB 1.x APIs.
+
+  <!-- TODO: verify where to host the spec that users can download.
+  This documentation is generated from the
+  [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml).
+  -->
+license:
+  name: MIT
+  url: 'https://opensource.org/licenses/MIT'
+contact:
+  name: InfluxData
+  url: https://www.influxdata.com
+  email: [email protected]

api-docs/influxdb3/core/v3/content/servers.yml

@@ -0,0 +1,8 @@
+- url: https://{baseurl}
+  description: InfluxDB 3 Core API URL
+  variables:
+    baseurl:
+      enum:
+        - 'localhost:8181'
+      default: 'localhost:8181'
+      description: InfluxDB 3 Core URL