API Ref docs processing (#3337)

* chore: API Reference Docs custom processing. Pulls contracts/ref files and applies custom content (tags, x-tagGroups, securitySchemes, info) before writing results to cloud/ref.yml and v2.0/ref.yml.
Rename source files from swagger.yml to ref.yml to avoid confusion and in case we need to bundle additional specs in the future.
Add an OpenAPI CLI docs-plugin with content and decorators.

* chore: update api-docs/README.md

* fix: add strip-version-prefix to remove /api/v2 added incorrectly to some paths during contract generation - also fixed in openapi repo so future contracts won't need this decorator. Fix server urls. Cleanup.

* chore: update cloud contract.

api-docs/.redocly.yaml

@@ -1,11 +1,8 @@
+apiDefintions:
+  main: ref.yaml
 lint:
+  plugins:
+    - './openapi/plugins/docs-plugin.js'
   extends:
     - recommended
-  plugins:
+    - docs/all
-    - './plugins/servers-plugin.js'
-  rules:
-    no-server-trailing-slash: off
-    servers/validate-servers-url: error
-  decorators:
-    servers/replace-servers-url: error
-    servers/set-servers-url: error

api-docs/README.md

@@ -2,7 +2,7 @@
 InfluxDB uses [Redoc](https://github.com/Redocly/redoc/),
 [redoc-cli](https://github.com/Redocly/redoc/blob/master/cli/README.md),
 and Redocly's [OpenApi CLI](https://redoc.ly/docs/cli/) to generate
-API documentation from the InfluxDB `swagger.yml`.
+API documentation from the InfluxDB openapi contracts.
 
 To minimize repo size, the generated API documentation HTML is gitignored, therefore
 not committed directly to the docs repo.
@@ -13,19 +13,28 @@ to generate version-specific API documentation.
 The structure versions swagger files using the following pattern:
 
 ```
-  │     └── swagger.yml
+api-docs/
+  ├── v2.0/
+  │     └── ref.yml
+  ├── v2.1/
+  │     └── ref.yml
+  ├── v2.2/
+  │     └── ref.yml
   └── etc...
 ```
 
-### OpenAPI CLI configuration
+### Configure OpenAPI CLI linting and bundling
 `.redoc.yaml` sets linting and bundling options for `openapi` CLI.
-`./plugins` contains custom OpenAPI CLI plugins composed of *rules* (for linting) and *decorators* (for bundle customization).
+`./openapi/plugins` contains custom OpenAPI CLI plugins composed of *rules* (for linting) and *decorators* (for bundle customization).
-api-docs/
+
-  ├── v2.0/
+### Custom content
-  │     └── swagger.yml
+`./openapi/content` contains custom OAS (OpenAPI Spec) content in YAML files. The content structure and Markdown must be valid OAS.
-  ├── v2.1/
+
-  │     └── swagger.yml
+`./openapi/plugins` use `./openapi/plugins/decorators` to apply the content to the contracts.
-  ├── v2.2/
+`.yml` files in `./openapi/content/` set content for sections (nodes) in the contract. To update the content for those nodes, you only need to update the YAML files.
+
+To add new YAML files for other nodes in the openapi contracts, configure the new content YAML file in `./openapi/content/content.js`. Then, write a decorator module for the node and configure the decorator in the plugin, e.g. `./openapi/plugins/docs-plugin.js`. See the [complete list of OAS v3.0 nodes](https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas3.ts#L529).
+
 `openapi` CLI requires that modules use CommonJS `require` syntax for imports. 
 
 ### Generate API docs locally

api-docs/generate-api-docs.sh

@@ -3,7 +3,7 @@
 set -e
 
 # Get list of versions from directory names
-versions="$(ls -d -- */ | grep -v 'node_modules' | grep -v 'plugins')"
+versions="$(ls -d -- */ | grep -v 'node_modules' | grep -v 'openapi')"
 
 for version in $versions
 do
@@ -46,12 +46,18 @@ weight: 304
   # npm_config_yes=true npx overrides the prompt
   # and (vs. npx --yes) is compatible with npm@6 and npm@7.
 
+  openapiCLI="@redocly/openapi-cli"
   redocCLI="redoc-cli@0.12.3"
 
   npm --version
 
+  # Use Redoc's openapi-cli to regenerate the spec with custom decorations.
+  INFLUXDB_VERSION=$version npm_config_yes=true npx $openapiCLI bundle $version/ref.yml \
+    --config=./.redocly.yaml \
+    -o $version/ref.yml
+
   # Use Redoc to generate the v2 API html
-  npm_config_yes=true npx $redocCLI bundle $version/swagger.yml \
+  npm_config_yes=true npx $redocCLI bundle $version/ref.yml \
     -t template.hbs \
     --title="InfluxDB $titleVersion API documentation" \
     --options.sortPropsAlphabetically \

api-docs/getswagger.sh

@@ -1,15 +1,15 @@
 #!/bin/bash -e
 
-# This script provides a simple way grab the latest fully resolved swagger files
+# This script provides a simple way grab the latest fully resolved openapi (OAS, OpenAPI Specification) contract files
 # from the influxdata/openapi repo.
 #
 # Specify a context to retrieve (cloud, oss, v1compat, all).
 # Optionally specify:
 # - an OSS version as the second argument or using the -o flag.
-#   The version specifies where to write the updated swagger.
+#   The version specifies where to write the updated openapi.
 #   The default version is the latest OSS version directory in the api-docs directory.
 # - a base URL using the -b flag.
-#   The baseURL specifies where to retrieve the swagger files from.
+#   The baseURL specifies where to retrieve the openapi files from.
 #   The default baseUrl is the master branch of the influxdata/openapi repo.
 #   For local development, pass your openapi directory using the file:/// protocol.
 #
@@ -88,17 +88,17 @@ function showArgs {
 }
 
 function updateCloud {
-  echo "Updating Cloud swagger..."
+  echo "Updating Cloud openapi..."
-  curl ${verbose} ${baseUrl}/contracts/ref/cloud.yml -s -o cloud/swagger.yml
+  curl ${verbose} ${baseUrl}/contracts/ref/cloud.yml -s -o cloud/ref.yml
 }
 
 function updateOSS {
-  echo "Updating OSS ${ossVersion} swagger..."
+  echo "Updating OSS ${ossVersion} openapi..."
-  mkdir -p ${ossVersion} && curl ${verbose} ${baseUrl}/contracts/ref/oss.yml -s -o $_/swagger.yml
+  mkdir -p ${ossVersion} && curl ${verbose} ${baseUrl}/contracts/ref/oss.yml -s -o $_/ref.yml
 }
 
 function updateV1Compat {
-  echo "Updating Cloud and ${ossVersion} v1 compatibilty swagger..."
+  echo "Updating Cloud and ${ossVersion} v1 compatibilty openapi..."
   curl ${verbose} ${baseUrl}/contracts/swaggerV1Compat.yml -s -o cloud/swaggerV1Compat.yml
   mkdir -p ${ossVersion} && cp cloud/swaggerV1Compat.yml $_/swaggerV1Compat.yml
 }

api-docs/openapi/content/cloud/info.yml

@@ -0,0 +1,3 @@
+title: Influx Cloud API Service
+description: |
+    The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.

api-docs/openapi/content/cloud/security-schemes.yml

@@ -0,0 +1,56 @@
+TokenAuthentication:
+  type: http
+  scheme: token
+  bearerFormat: InfluxDB Token String
+  description: |
+    ### Token authentication scheme
+
+    InfluxDB API tokens ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization.
+
+    Include your API token in an `Authentication: Token YOUR_API_TOKEN` HTTP header with each request.
+
+    ### Example
+
+    `curl https://us-east-1-1.aws.cloud2.influxdata.com/
+          --header "Authentication: Token YOUR_API_TOKEN"`
+
+    For more information and examples, see the following:
+      - [Use tokens in API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication).
+      - [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens).
+      - [`/authorizations`](#tag/Authorizations) endpoint.
+BasicAuthentication:
+  type: http
+  scheme: basic
+  description: |
+    ### Basic authentication scheme
+
+    Use HTTP Basic Auth with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
+      - **username**: InfluxDB Cloud username
+      - **password**: InfluxDB Cloud API token
+
+    ### Example
+
+    `curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query"
+          --user "YOUR_USERNAME":"YOUR_TOKEN_OR_PASSWORD"`
+
+    For more information and examples, see how to [authenticate with a username and password scheme](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/).
+QuerystringAuthentication:
+  type: apiKey
+  in: query
+  name: u=&p=
+  description: |
+    ### Querystring authentication scheme
+
+    Use InfluxDB 1.x API parameters to provide credentials through the query string.
+
+    Username and password schemes require the following credentials:
+    - **username**: InfluxDB Cloud username
+    - **password**: InfluxDB Cloud API token
+
+    ### Example
+
+    `curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query"
+          --data-urlencode "u=YOUR_USERNAME"
+          --data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"`
+
+    For more information and examples, see how to [authenticate with a username and password scheme](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/).

api-docs/openapi/content/cloud/servers.yml

@@ -0,0 +1,8 @@
+- url: https://{baseurl}
+  description: InfluxDB Cloud API URL
+  variables:
+    baseurl:
+      enum:
+        - 'us-east-1-1.aws.cloud2.influxdata.com'
+      default: 'us-east-1-1.aws.cloud2.influxdata.com'
+      description: InfluxDB Cloud URL

api-docs/openapi/content/cloud/tag-groups.yml

@@ -0,0 +1,26 @@
+- name: Overview
+  tags:
+    - Quick start
+    - Authentication
+    - Response codes
+- name: Data I/O endpoints
+  tags:
+    - Write
+    - Query
+- name: Resource endpoints
+  tags:
+    - Buckets
+    - Dashboards
+    - Tasks
+    - Resources
+- name: Security and access endpoints
+  tags:
+    - Authorizations
+    - Organizations
+    - Users
+- name: System information endpoints
+  tags:
+    - Ping
+    - Routes
+- name: All endpoints
+  tags: []

api-docs/openapi/content/cloud/tags.yml

@@ -0,0 +1,58 @@
+- name: Quick start
+  description: Some quickness
+  x-traitTag: true
+- name: Authentication
+  description: |
+    Use one of the following schemes to authenticate to the InfluxDB API:
+    - [Token authentication](#section/Authentication/TokenAuthentication)
+    - [Basic authentication](#section/Authentication/BasicAuthentication)
+    - [Querystring authentication](#section/Authentication/QuerystringAuthentication)
+    <!-- ReDoc-Inject: <security-definitions> -->
+  x-traitTag: true
+- name: Invocable Scripts
+  description: |
+    Manage and execute scripts as API endpoints in InfluxDB.
+
+    An API Invocable Script assigns your custom Flux script to a new InfluxDB API endpoint for your organization.
+    Invocable scripts let you execute your script as an HTTP request to the endpoint.
+
+    Invocable scripts accept parameters. Add parameter references in your script as `params.myparameter`.
+    When you `invoke` your script, you send parameters as key-value pairs in the `params` object.
+    InfluxDB executes your script with the key-value pairs as arguments and returns the result.
+
+    For more information and examples, see [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invocable-scripts).
+- name: Quick start
+  x-traitTag: true
+  description: |
+    See the [**API Quick Start**](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data.
+
+    [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/) are available for popular languages and ready to import into your application.
+- name: Response codes
+  x-traitTag: true
+  description: |
+    The InfluxDB API uses standard HTTP status codes for success and failure responses.
+    The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation.
+
+    API operations may return the following HTTP status codes:
+
+    | &nbsp;Code&nbsp; | Status                   | Description      |
+    |:-----------:|:------------------------ |:--------------------- |
+    | `200`       | Success                  |                       |
+    | `204`       | No content               | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
+    | `400`       | Bad request              | `Authorization` header is missing or malformed or the API token does not have permission for the operation. |
+    | `401`       | Unauthorized             | May indicate one of the following: <li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token does not have permission. For more information about token types and permissions, see [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/)</li> |
+    | `404`       | Not found                | Requested resource was not found. `message` in the response body provides details about the requested resource. |
+    | `413`       | Request entity too large | Request payload exceeds the size limit. |
+    | `422`       | Unprocessible entity     | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
+    | `429`       | Too many requests        | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
+    | `500`       | Internal server error    |                       |
+    | `503`       | Service unavailable      | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
+- name: Query
+  description: |
+    Retrieve data, analyze queries, and get query suggestions.
+- name: Write
+  description: |
+    Write time series data to buckets.
+- name: Authorizations
+  description: |
+    Create and manage API tokens. An **authorization** associates a list of permissions to an **organization** and provides a token for API access. To assign a token to a specific user, scope the authorization to the user ID.

api-docs/openapi/content/content.js

@@ -0,0 +1,25 @@
+const path = require('path');
+const { toJSON } = require('../plugins/helpers/content-helper');
+
+function getVersion(filename) {
+  return path.join(__dirname, process.env.INFLUXDB_VERSION, filename);
+}
+
+const info = toJSON(getVersion('info.yml'));
+
+const securitySchemes = toJSON(getVersion('security-schemes.yml'));
+
+const servers = toJSON(path.join(__dirname, 'servers.yml'));
+
+const tags = toJSON(getVersion('tags.yml'));
+
+const tagGroups = toJSON(getVersion('tag-groups.yml'));
+
+module.exports = {
+  info,
+  securitySchemes,
+  servers,
+  tagGroups,
+  tags,
+}
+

api-docs/openapi/content/servers.yml

@@ -0,0 +1 @@
+- url: '/'

api-docs/openapi/content/v2.0/info.yml

@@ -0,0 +1,3 @@
+title: Influx OSS API Service
+description: |
+    The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.

api-docs/openapi/content/v2.0/security-schemes.yml

@@ -0,0 +1,58 @@
+TokenAuthentication:
+  type: http
+  scheme: token
+  bearerFormat: InfluxDB Token String
+  description: |
+    ### Token authentication scheme
+
+    InfluxDB API tokens ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization.
+
+    Include your API token in an `Authentication: Token YOUR_API_TOKEN` HTTP header with each request.
+
+    ### Example
+
+      `curl http://localhost:8086/ping
+          --header "Authentication: Token YOUR_API_TOKEN"`
+
+    For more information and examples, see the following:
+      - [Use tokens in API requests](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/#authentication).
+      - [Manage API tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens).
+      - [`/authorizations`](#tag/Authorizations) endpoint.
+BasicAuthentication:
+  type: http
+  scheme: basic
+  description: |
+    ### Basic authentication scheme
+
+    Use HTTP Basic Auth with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme).
+
+    Username and password schemes require the following credentials:
+      - **username**: 1.x username (this is separate from the UI login username)
+      - **password**: 1.x password or InfluxDB API token
+
+    ### Example
+
+    `curl --get "http://localhost:8086/query"
+          --user "YOUR_1.x_USERNAME":"YOUR_TOKEN_OR_PASSWORD"`
+
+    For more information and examples, see how to [authenticate with a username and password scheme](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/)
+QuerystringAuthentication:
+  type: apiKey
+  in: query
+  name: u=&p=
+  description: |
+    ### Querystring authentication scheme
+
+    Use InfluxDB 1.x API parameters to provide credentials through the query string.
+
+    Username and password schemes require the following credentials:
+      - **username**: 1.x username (this is separate from the UI login username)
+      - **password**: 1.x password or InfluxDB API token
+
+    ### Example
+
+    `curl --get "http://localhost:8086/query"
+          --data-urlencode "u=YOUR_1.x_USERNAME"
+          --data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"`
+
+    For more information and examples, see how to [authenticate with a username and password scheme](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/)

api-docs/openapi/content/v2.0/tag-groups.yml

@@ -0,0 +1,28 @@
+- name: Overview
+  tags:
+    - Quick start
+    - Authentication
+    - Response codes
+- name: Data I/O endpoints
+  tags:
+    - Write
+    - Query
+- name: Resource endpoints
+  tags:
+    - Buckets
+    - Dashboards
+    - Tasks
+    - Resources
+- name: Security and access endpoints
+  tags:
+    - Authorizations
+    - Organizations
+    - Users
+- name: System information endpoints
+  tags:
+    - Health
+    - Ping
+    - Ready
+    - Routes
+- name: All endpoints
+  tags: []

api-docs/openapi/content/v2.0/tags.yml

@@ -0,0 +1,43 @@
+- name: Authentication
+  description: |
+    Use one of the following schemes to authenticate to the InfluxDB API:
+    - [Token authentication](#section/Authentication/TokenAuthentication)
+    - [Basic authentication](#section/Authentication/BasicAuthentication)
+    - [Querystring authentication](#section/Authentication/QuerystringAuthentication)
+    <!-- ReDoc-Inject: <security-definitions> -->
+  x-traitTag: true
+- name: Quick start
+  x-traitTag: true
+  description: |
+    See the [**API Quick Start**](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data.
+
+    [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/v2.0/api-guide/client-libraries/) are available for popular languages and ready to import into your application.
+- name: Response codes
+  x-traitTag: true
+  description: |
+    The InfluxDB API uses standard HTTP status codes for success and failure responses.
+    The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation.
+
+    API operations may return the following HTTP status codes:
+
+    | &nbsp;Code&nbsp; | Status                   | Description      |
+    |:-----------:|:------------------------ |:--------------------- |
+    | `200`       | Success                  |                       |
+    | `204`       | No content               | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
+    | `400`       | Bad request              | `Authorization` header is missing or malformed or the API token does not have permission for the operation. |
+    | `401`       | Unauthorized             | May indicate one of the following: <li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token does not have permission. For more information about token types and permissions, see [Manage API tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/)</li> |
+    | `404`       | Not found                | Requested resource was not found. `message` in the response body provides details about the requested resource. |
+    | `413`       | Request entity too large | Request payload exceeds the size limit. |
+    | `422`       | Unprocessible entity     | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
+    | `429`       | Too many requests        | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
+    | `500`       | Internal server error    |                       |
+    | `503`       | Service unavailable      | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
+- name: Query
+  description: |
+    Retrieve data, analyze queries, and get query suggestions.
+- name: Write
+  description: |
+    Write time series data to buckets.
+- name: Authorizations
+  description: |
+    Create and manage API tokens. An **authorization** associates a list of permissions to an **organization** and provides a token for API access. To assign a token to a specific user, scope the authorization to the user ID.

api-docs/openapi/plugins/decorators/paths/remove-private-paths.js

@@ -0,0 +1,17 @@
+module.exports = RemovePrivatePaths;
+
+/** @type {import('@redocly/openapi-cli').OasDecorator} */
+function RemovePrivatePaths() {
+  return {
+    PathItem: {
+      leave(pathItem, ctx) {
+        const private = /\/.*private/;
+        if(private.test(ctx.key)) {
+          delete ctx.parent[ctx.key];
+	}
+      }
+    }
+  }
+}
+
+

api-docs/openapi/plugins/decorators/paths/strip-version-prefix.js

@@ -0,0 +1,28 @@
+module.exports = StripVersionPrefix;
+
+/** @type {import('@redocly/openapi-cli').OasDecorator} */
+function StripVersionPrefix() {
+  return {
+    PathMap: {
+      leave(paths, ctx) {
+        const nonversioned = [
+          '/health',
+          '/legacy/authorizations',
+          '/legacy/authorizations/{authID}',
+          '/legacy/authorizations/{authID}/password',
+          '/ping',
+          '/ready'
+        ];
+        const prefix = '/api/v2';
+        nonversioned.forEach(function(nv) {
+          const path = JSON.stringify(paths[prefix + nv]);
+          if(path) {
+            delete paths[prefix + nv];
+            paths[nv] = JSON.parse(path);
+          }
+        });
+      }
+    }
+  }
+}
+

api-docs/openapi/plugins/decorators/security/set-security-schemes.js

@@ -0,0 +1,18 @@
+module.exports = SetSecuritySchemes;
+
+/** @type {import('@redocly/openapi-cli').OasDecorator} */
+function SetSecuritySchemes(options) {
+  return {
+    Components: {
+      leave(comps, ctx) {
+	if(options.data) {
+	  comps.securitySchemes = comps.securitySchemes || {};
+	  Object.keys(options.data).forEach(
+	    function(scheme) {
+              comps.securitySchemes[scheme] = options.data[scheme];
+            })
+	}
+      }
+    }
+  }
+}

api-docs/openapi/plugins/decorators/servers/set-servers.js

@@ -1,4 +1,4 @@
-module.exports = SetServersURL;
+module.exports = SetServers;
 
 /** @type {import('@redocly/openapi-cli').OasDecorator} */
 
@@ -7,15 +7,12 @@ module.exports = SetServersURL;
  * The key instructs openapi when to invoke the key's Visitor object. 
  * Object key "Server" is an OAS 3.0 node type.
  */
-function SetServersURL() {
+function SetServers(options) {
   return {
-    Operation: {
+    DefinitionRoot: {
-      leave(operation, ctx) {
+      leave(root) {
-	const operations = ['GetRoutes']
+        root.servers = options.data;
-        if(operations.includes(operation.operationId)) {
-		operation.servers = [{url: '/'}];
-	}
       }
-    }
+    },
   }
 };

api-docs/openapi/plugins/decorators/set-info.js

@@ -0,0 +1,15 @@
+module.exports = SetInfo;
+
+/** @type {import('@redocly/openapi-cli').OasDecorator} */
+function SetInfo(options) {
+  return {
+    Info: {
+      leave(info, ctx) {
+        if(options.data) {
+	  info.title = options.data.title;
+	  info.description = options.data.description;
+	}
+      }
+    }
+  }
+}

api-docs/openapi/plugins/decorators/tags/set-tag-groups.js

@@ -0,0 +1,44 @@
+module.exports = SetTagGroups;
+
+const { collect, getName, sortName } = require('../../helpers/content-helper.js')
+/**
+ * Returns an object that defines handler functions for:
+ * - Operation nodes
+ * - DefinitionRoot (the root openapi) node
+ * The order of the two functions is significant.
+ * The Operation handler collects tags from the 
+ * operation ('get', 'post', etc.) in every path.
+ * The DefinitionRoot handler, executed when
+ * the parser is leaving the root node,
+ * sets `x-tagGroups` to the provided `data`
+ * and sets the value of `All Endpoints` to the collected tags.
+ */
+/** @type {import('@redocly/openapi-cli').OasDecorator} */
+function SetTagGroups(options) {
+  let tags = [];
+  return {
+    Operation: {
+      leave(op, ctx, parents) {
+        tags = collect(tags, op.tags);
+      }
+    },
+    DefinitionRoot: {
+      leave(root) {
+	root.tags = root.tags || [];
+	root.tags = collect(root.tags, tags)
+	  .sort((a, b) => sortName(a, b));
+
+	if(!options.data) { return; }
+
+	endpointTags = root.tags
+	  .filter(t => !t['x-traitTag'])
+	  .map(t => getName(t));
+	root['x-tagGroups'] = options.data
+	  .map(function(grp) {
+	    grp.tags = grp.name === 'All endpoints' ? endpointTags : grp.tags;
+	    return grp;
+	  });
+      }
+    }
+  }
+};

api-docs/openapi/plugins/decorators/tags/set-tags.js

@@ -0,0 +1,22 @@
+module.exports = SetTags;
+
+/**
+ * Returns an object that defines handler functions for:
+ * - DefinitionRoot (the root openapi) node
+ * The DefinitionRoot handler, executed when
+ * the parser is leaving the root node,
+ * sets the root `tags` list to the provided `data`. 
+ */
+/** @type {import('@redocly/openapi-cli').OasDecorator} */
+function SetTags(options) {
+  let tags = [];
+  return {
+    DefinitionRoot: {
+      leave(root) {
+	if(options.data) {
+          root.tags = options.data;
+	}
+      }
+    }
+  }
+};

api-docs/openapi/plugins/docs-plugin.js

@@ -0,0 +1,57 @@
+const ReportTags = require('./rules/report-tags');
+const ValidateServersUrl = require('./rules/validate-servers-url');
+const RemovePrivatePaths = require('./decorators/paths/remove-private-paths');
+const SetInfo = require('./decorators/set-info');
+const SetServers = require('./decorators/servers/set-servers');
+const SetSecuritySchemes = require('./decorators/security/set-security-schemes');
+const SetTags = require('./decorators/tags/set-tags');
+const SetTagGroups = require('./decorators/tags/set-tag-groups');
+const StripVersionPrefix = require('./decorators/paths/strip-version-prefix');
+const {info, securitySchemes, servers, tags, tagGroups } = require('../content/content')
+
+const id = 'docs';
+
+/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
+const rules = {
+  oas3: {
+    'validate-servers-url': ValidateServersUrl,
+    'report-tags': ReportTags,
+  }
+};
+
+/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
+const decorators = {
+  oas3: {
+    'set-servers': () => SetServers({data: servers}),
+    'remove-private-paths': RemovePrivatePaths,
+    'strip-version-prefix': StripVersionPrefix,
+    'set-info': () => SetInfo({data: info}),
+    'set-security': () => SetSecurity({data: security}),
+    'set-security-schemes': () => SetSecuritySchemes({data: securitySchemes}),
+    'set-tags': () => SetTags({data: tags}),
+    'set-tag-groups': () => SetTagGroups({data: tagGroups}),
+  }
+};
+
+module.exports = {
+  id,
+  configs: {
+    all: {
+      rules: {
+	'no-server-trailing-slash': 'off',
+        'docs/validate-servers-url': 'error',
+      },
+      decorators: {
+        'docs/set-servers': 'error',
+	'docs/remove-private-paths': 'error',
+	'docs/strip-version-prefix': 'error',
+	'docs/set-info': 'error',
+	'docs/set-security-schemes': 'error',
+        'docs/set-tags': 'error',
+	'docs/set-tag-groups': 'error',
+      },
+    },
+  },
+  decorators,
+  rules
+};

api-docs/openapi/plugins/helpers/content-helper.js

@@ -0,0 +1,65 @@
+const yaml = require('js-yaml');
+const fs = require('fs');
+
+function getName(item) {
+  if(typeof(item) === 'string') {
+    return item;
+  }
+  if(item.hasOwnProperty('name')) {
+    return item.name;
+  }
+}
+
+function sortName(a, b) {
+  let nameA = getName(a)
+  nameA = nameA.toUpperCase();
+  let nameB = getName(b)
+  nameB = nameB.toUpperCase();
+  if(nameA < nameB) {
+    return -1;
+  }
+  if(nameA > nameB) {
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Returns true if item or item.name exists in collection
+ */
+function isPresent(collection, item) {
+  const itemName = getName(item);
+  return (
+    collection.indexOf(itemName) > -1 
+    || collection.filter(ci => ci.name && ci.name === itemName).length > 0
+  );
+}
+
+/**
+ * Merges items from Array items to Array collection and removes duplicates from collection.
+ *
+ */
+function collect(collection, items) {
+  if(Array.isArray(items)) {
+    collection = collection
+      .concat(items.filter(item => !isPresent(collection, item))); 
+  }
+  return collection;
+}
+
+function toJSON(yamlPath) {
+  try {
+    return yaml.load(fs.readFileSync(yamlPath, 'utf8'));
+  } catch (e) {
+    console.log(e);
+  }
+}
+
+module.exports = {
+  collect,
+  getName,
+  isPresent,
+  sortName,
+  toJSON,
+}
+

api-docs/openapi/plugins/rules/report-tags.js

@@ -0,0 +1,18 @@
+module.exports = ReportTags 
+
+ /**
+  * Reports on tags.
+  */
+/** @type {import('@redocly/openapi-cli').OasRule} */
+function ReportTags() {
+  return {
+    DefinitionRoot: {
+      Tag(node, ctx) {
+          ctx.report({
+            message: `tags`,
+            location: ctx.location.pointer
+          })
+      }
+    }
+  }
+}

api-docs/package.json

@@ -3,5 +3,8 @@
   "name": "api-docs",
   "version": "1.0.0",
   "description": "InfluxDB API documentation",
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
 }

api-docs/plugins/decorators/replace-servers-url.js

@@ -1,20 +0,0 @@
-module.exports = ReplaceRootURL;
-
-/** @type {import('@redocly/openapi-cli').OasDecorator} */
-
-/**
- * Returns an object with keys in [node type, any, ref].
- * The key instructs openapi when to invoke the key's Visitor object. 
- * Object key "Server" is an OAS 3.0 node type.
- */
-function ReplaceRootURL() {
-  return {
-    Operation: {
-      leave(operation, ctx) {
-        if(Array.isArray(operation.servers)) {
-	  operation.servers.forEach(server => server.url = server.url === '' ? '/' : server.url);
-	}
-      }
-    }
-  }
-};

api-docs/plugins/servers-plugin.js

@@ -1,28 +0,0 @@
-const ReplaceServersUrl = require('./decorators/replace-servers-url');
-const SetServersUrl = require('./decorators/set-servers-url');
-const ValidateServersUrl = require('./rules/validate-servers-url');
-const id = 'servers';
-
-/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
-const rules = {
-  oas3: {
-    'validate-servers-url': ValidateServersUrl  
-  }
-}
-
-/** @type {import('@redocly/openapi-cli').CustomRulesConfig} */
-const decorators = {
-  oas3: {
-    'replace-servers-url': ReplaceServersUrl,
-    'set-servers-url': SetServersUrl
-  }
-};
-
-module.exports = {
-  id,
-  configs: {
-    all: {rules, decorators},
-  },
-  rules,
-  decorators
-};

api-docs/yarn.lock

@@ -2,4 +2,14 @@
 # yarn lockfile v1
 
 
+argparse@^2.0.1:
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38"
+  integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==
 
+js-yaml@^4.1.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.0.tgz#c1fb65f8f5017901cdd2c951864ba18458a10602"
+  integrity sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==
+  dependencies:
+    argparse "^2.0.1"