docs(savanna): use the same API key auth on org user pages

lib/api-descriptions.json

@@ -33,7 +33,7 @@
     "GET /controller/v4/v2/workgroups/{workgroupID}/allow_list": "Lists the IP addresses and CIDR ranges permitted by a workgroup allow list.",
     "GET /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/backups": "Lists the backups for a workspace.",
     "GET /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/dbuser": "Lists the in-database GSQL users for a workspace.",
-    "GET /users": "Lists the users in your organization. This endpoint does not support API key authentication.",
+    "GET /users": "Lists the users in your organization.",
     "GET /controller/v4/v2/workgroups": "Lists the workgroups in your organization.",
     "GET /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/schedules": "Lists the schedules for a workspace.",
     "POST /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/pause": "Pauses a workspace.",
@@ -47,7 +47,7 @@
     "PUT /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}": "Updates a workspace configuration.",
     "PUT /controller/v4/v2/workgroups/{workgroupID}/allow_list/{id}": "Updates an entry in a workgroup allow list.",
     "PUT /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/dbuser": "Updates an in-database GSQL user's password.",
-    "PUT /users/{userId}/roles": "Updates an organization user's role. This endpoint does not support API key authentication.",
+    "PUT /users/{userId}/roles": "Updates an organization user's role.",
     "GET /controller/v4/v2/addons/meta": "Lists the add-ons available to your organization. Use an id from this list as addons_id when you install an add-on or enable one on a workspace.",
     "POST /controller/v4/v2/addons/{addonsID}/install": "Installs an add-on for your organization, or enables or disables it.",
     "GET /controller/v4/v2/installed-addons": "Lists the add-ons installed for your organization.",

lib/api-page.js

@@ -15,6 +15,10 @@ const fs = require('fs')
 const path = require('path')
 
 const BASE_URL = 'https://api.tgcloud.io'
+// Replaced in lib/split-endpoints.js with an AsciiDoc xref. A hand-written
+// href cannot be used here: production drops the .html extension and then
+// rewrites leftover .html links to site-root paths, which 404 under /docs.
+const API_KEY_XREF_MARKER = '@@API_KEY_XREF@@'
 // Deep enough for every schema in the current spec; only a guard against a
 // pathological one. Recursion already stops when a definition repeats.
 const MAX_DEPTH = 12
@@ -262,13 +266,7 @@ function renderAuthorizations (operation, pad) {
           '<p>' + escapeHtml(scheme.description) + '. Send the key in the <code>' +
           escapeHtml(scheme.name) + '</code> request ' + scheme.in + '.</p>'
       )
-      // The publisher only rewrites in-content links that carry Antora's xref
-      // classes; without them this relative href is resolved against the site
-      // root and loses the /docs base path.
-      out.push(
-        indent(pad + 4) +
-          '<a href="../create-api-key.html" class="xref page">Create an API key</a>'
-      )
+      out.push(API_KEY_XREF_MARKER)
       out.push(indent(pad + 2) + '</div>')
     }
   }
@@ -654,4 +652,4 @@ function renderApiPage (endpoint) {
   return out.join('\n')
 }
 
-module.exports = { renderApiPage }
+module.exports = { renderApiPage, API_KEY_XREF_MARKER }

lib/split-endpoints.js

@@ -14,7 +14,8 @@
 
 const fs = require('fs')
 const path = require('path')
-const { renderApiPage } = require('./api-page')
+const { renderApiPage, API_KEY_XREF_MARKER } = require('./api-page')
+const API_KEY_XREF = 'xref:rest-api:create-api-key.adoc[Create an API key]'
 
 const MODULE_DIR = path.join(__dirname, '..', 'modules/savanna/modules/rest-api')
 const CATALOG = path.join(MODULE_DIR, '_catalog/endpoints.adoc')
@@ -151,16 +152,20 @@ function parseCatalog (text) {
 }
 
 function renderPage (endpoint, label) {
-  return [
-    '= ' + label,
-    ':page-role: api-endpoint-detail',
-    GENERATED,
-    '',
-    '++++',
-    renderApiPage(endpoint),
-    '++++',
-    '',
-  ].join('\n')
+  // The xref has to be AsciiDoc, not a raw <a href="../create-api-key.html">.
+  // Production uses html_extension_style: drop, then rewrites any leftover
+  // .html href into a root-absolute path (/savanna/...). That URL 404s on
+  // www.tigergraph.com/docs because the /docs prefix is not part of the path.
+  // Antora resolves this xref to a relative, extensionless URL, which is what
+  // every other in-content link on the site already uses.
+  const chunks = renderApiPage(endpoint).split(API_KEY_XREF_MARKER)
+  const blocks = []
+  chunks.forEach((chunk, index) => {
+    blocks.push('++++', chunk.replace(/^\n/, '').replace(/\n$/, ''), '++++')
+    if (index === chunks.length - 1) return
+    blocks.push('', '[subs=macros]', '++++', API_KEY_XREF, '++++', '')
+  })
+  return ['= ' + label, ':page-role: api-endpoint-detail', GENERATED, '', ...blocks, ''].join('\n')
 }
 
 function renderNav (grouped) {

modules/savanna/modules/rest-api/_catalog/endpoints.adoc

@@ -2643,7 +2643,7 @@ GET https://api.tgcloud.io/users
 
 [discrete]
 ==== Description
-List of users in the org. Note: this endpoint is not APIKEY compatible
+List of users in the org.
 
 [discrete]
 ==== Responses
@@ -2678,7 +2678,7 @@ PUT https://api.tgcloud.io/users/{userId}/roles
 
 [discrete]
 ==== Description
-Updates the role of an org user. Note: this endpoint is not APIKEY compatible
+Updates the role of an org user.
 
 [discrete]
 ==== Parameters

modules/savanna/modules/rest-api/_catalog/openapi.json

@@ -6391,7 +6391,7 @@
     "consumes": [
      "application/json"
     ],
-    "description": "List of users in the org. Note: this endpoint is not APIKEY compatible",
+    "description": "List of users in the org.",
     "produces": [
      "application/json"
     ],
@@ -6403,6 +6403,11 @@
       }
      }
     },
+    "security": [
+     {
+      "ApiKeyAuth": []
+     }
+    ],
     "summary": "List of users in the org",
     "tags": [
      "Org"
@@ -6414,7 +6419,7 @@
     "consumes": [
      "application/json"
     ],
-    "description": "Updates the role of an org user. Note: this endpoint is not APIKEY compatible",
+    "description": "Updates the role of an org user.",
     "parameters": [
      {
       "description": "Id of the user",
@@ -6441,6 +6446,11 @@
       "description": "No Content"
      }
     },
+    "security": [
+     {
+      "ApiKeyAuth": []
+     }
+    ],
     "summary": "Update the role of an org user",
     "tags": [
      "Org"

modules/savanna/modules/rest-api/pages/endpoints/add-an-allowed-ip.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/check-the-current-ip.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/create-a-cloud-provider.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-body-title">

modules/savanna/modules/rest-api/pages/endpoints/create-a-workgroup.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-body-title">

modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace-schedule.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/create-an-add-on-configuration.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/create-an-in-database-user.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/delete-a-backup.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/delete-a-cloud-provider.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/delete-a-database.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/delete-a-workgroup.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace-schedule.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">

modules/savanna/modules/rest-api/pages/endpoints/delete-an-add-on-configuration.adoc

@@ -31,7 +31,14 @@
             <span class="api-required">required</span>
           </div>
           <p>Authorization for TigerGraph Savanna. Send the key in the <code>x-api-key</code> request header.</p>
-          <a href="../create-api-key.html" class="xref page">Create an API key</a>
+++++
+
+[subs=macros]
+++++
+xref:rest-api:create-api-key.adoc[Create an API key]
+++++
+
+++++
         </div>
       </section>
       <section class="api-section" aria-labelledby="api-path-parameters-title">