feat(admin): document admin endpoints in OpenAPI (#7693)

admin/scripts/__tests__/merge-openapi.test.mjs

@@ -0,0 +1,74 @@
+import {test} from 'node:test';
+import {strict as assert} from 'node:assert';
+import {mergeOpenAPI} from '../merge-openapi.mjs';
+
+const minimal = (overrides = {}) => ({
+  openapi: '3.0.2',
+  info: {title: 'X', version: '0.0.0'},
+  paths: {},
+  components: {schemas: {}, securitySchemes: {}},
+  ...overrides,
+});
+
+test('unions paths from both docs', () => {
+  const pub = minimal({paths: {'/createGroup': {post: {operationId: 'createGroup'}}}});
+  const adm = minimal({paths: {'/admin-auth/': {post: {operationId: 'verifyAdminAccess'}}}});
+  const out = mergeOpenAPI(pub, adm);
+  assert.deepEqual(Object.keys(out.paths).sort(), ['/admin-auth/', '/createGroup']);
+});
+
+test('throws on path collision', () => {
+  const pub = minimal({paths: {'/x': {get: {}}}});
+  const adm = minimal({paths: {'/x': {post: {}}}});
+  assert.throws(() => mergeOpenAPI(pub, adm), /path collision/i);
+});
+
+test('unions components.schemas', () => {
+  const pub = minimal({components: {schemas: {A: {}}, securitySchemes: {}}});
+  const adm = minimal({components: {schemas: {B: {}}, securitySchemes: {}}});
+  const out = mergeOpenAPI(pub, adm);
+  assert.deepEqual(Object.keys(out.components.schemas).sort(), ['A', 'B']);
+});
+
+test('throws on schema name collision', () => {
+  const pub = minimal({components: {schemas: {Dup: {}}, securitySchemes: {}}});
+  const adm = minimal({components: {schemas: {Dup: {}}, securitySchemes: {}}});
+  assert.throws(() => mergeOpenAPI(pub, adm), /schema collision/i);
+});
+
+test('unions securitySchemes', () => {
+  const pub = minimal({components: {schemas: {}, securitySchemes: {apiKey: {}}}});
+  const adm = minimal({components: {schemas: {}, securitySchemes: {basicAuth: {}}}});
+  const out = mergeOpenAPI(pub, adm);
+  assert.deepEqual(
+    Object.keys(out.components.securitySchemes).sort(),
+    ['apiKey', 'basicAuth'],
+  );
+});
+
+test('preserves public root security; admin per-operation security survives', () => {
+  const pub = minimal({security: [{apiKey: []}]});
+  const adm = minimal({
+    paths: {
+      '/admin-auth/': {
+        post: {
+          security: [{basicAuth: []}, {}],
+        },
+      },
+    },
+  });
+  const out = mergeOpenAPI(pub, adm);
+  assert.deepEqual(out.security, [{apiKey: []}]);
+  assert.deepEqual(
+    out.paths['/admin-auth/'].post.security,
+    [{basicAuth: []}, {}],
+  );
+});
+
+test('public info wins on conflict', () => {
+  const pub = minimal({info: {title: 'Public', version: '1.0'}});
+  const adm = minimal({info: {title: 'Admin', version: '2.0'}});
+  const out = mergeOpenAPI(pub, adm);
+  assert.equal(out.info.title, 'Public');
+  assert.equal(out.info.version, '1.0');
+});

admin/scripts/dump-spec.ts

@@ -1,16 +1,18 @@
 // admin/scripts/dump-spec.ts
 //
-// Imports the OpenAPI spec builder from the etherpad source and writes the
-// flat-style spec for the latest API version as JSON to the file path passed
-// as argv[2]. Invoked by admin/scripts/gen-api.mjs via `tsx`.
+// Imports the public + admin OpenAPI spec builders from the etherpad
+// source, merges them into one document, and writes JSON to argv[2].
+// Invoked by admin/scripts/gen-api.mjs via `tsx`.
 //
-// Why a file argument instead of stdout: importing `openapi.ts` triggers
-// `Settings` init, which configures log4js to write INFO/WARN lines to
+// Why a file argument instead of stdout: importing openapi*.ts triggers
+// Settings init, which configures log4js to write INFO/WARN lines to
 // stdout. Capturing stdout would mix logs with JSON.
 
-import { writeFileSync } from 'node:fs';
+import {writeFileSync} from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+// @ts-expect-error — sibling .mjs has no .d.ts; tsx resolves it at runtime.
+import {mergeOpenAPI} from './merge-openapi.mjs';
 
 const outFile = process.argv[2];
 if (!outFile) {
@@ -23,24 +25,33 @@ const repoRoot = path.resolve(here, '..', '..');
 
 const apiHandlerPath = path.join(repoRoot, 'src', 'node', 'handler', 'APIHandler.ts');
 const openapiPath = path.join(repoRoot, 'src', 'node', 'hooks', 'express', 'openapi.ts');
+const openapiAdminPath = path.join(
+  repoRoot, 'src', 'node', 'hooks', 'express', 'openapi-admin.ts',
+);
 
-// `openapi.ts` and `APIHandler.ts` use CommonJS-style `exports.*`. Under tsx's
-// ESM dynamic import, the whole `module.exports` is exposed as `default`.
-type ApiHandlerModule = { latestApiVersion: string };
+type ApiHandlerModule = {latestApiVersion: string};
 type OpenApiModule = {
   generateDefinitionForVersion: (version: string, style?: string) => unknown;
-  APIPathStyle: { FLAT: string; REST: string };
+  APIPathStyle: {FLAT: string; REST: string};
+};
+type OpenApiAdminModule = {
+  generateAdminDefinition: () => unknown;
 };
 
 const apiHandlerMod = await import(pathToFileURL(apiHandlerPath).href);
 const openapiMod = await import(pathToFileURL(openapiPath).href);
+const openapiAdminMod = await import(pathToFileURL(openapiAdminPath).href);
 
 const apiHandler = (apiHandlerMod.default ?? apiHandlerMod) as ApiHandlerModule;
 const openapi = (openapiMod.default ?? openapiMod) as OpenApiModule;
+const openapiAdmin = (openapiAdminMod.default ?? openapiAdminMod) as OpenApiAdminModule;
 
-const spec = openapi.generateDefinitionForVersion(
+const publicSpec = openapi.generateDefinitionForVersion(
   apiHandler.latestApiVersion,
   openapi.APIPathStyle.FLAT,
 );
+const adminSpec = openapiAdmin.generateAdminDefinition();
+
+const merged = mergeOpenAPI(publicSpec, adminSpec);
 
-writeFileSync(path.resolve(outFile), JSON.stringify(spec, null, 2), 'utf8');
+writeFileSync(path.resolve(outFile), JSON.stringify(merged, null, 2), 'utf8');

admin/scripts/merge-openapi.mjs

@@ -0,0 +1,56 @@
+// admin/scripts/merge-openapi.mjs
+//
+// Deep-merges the public-API OpenAPI document with the admin OpenAPI
+// document into a single document for openapi-typescript to consume.
+//
+// Rules:
+//   - paths: union by key; collision throws
+//   - components.{schemas,parameters,responses,securitySchemes}: union by name; collision throws
+//   - root info, servers, security: public wins (admin's are ignored at the root)
+//   - per-operation security on admin paths is preserved untouched
+
+const unionMap = (label, a = {}, b = {}) => {
+  const out = {...a};
+  for (const [k, v] of Object.entries(b)) {
+    if (k in out) {
+      throw new Error(`${label} on key "${k}"`);
+    }
+    out[k] = v;
+  }
+  return out;
+};
+
+export const mergeOpenAPI = (publicDoc, adminDoc) => {
+  if (!publicDoc || !adminDoc) {
+    throw new Error('mergeOpenAPI requires both publicDoc and adminDoc');
+  }
+  return {
+    openapi: publicDoc.openapi || adminDoc.openapi,
+    info: publicDoc.info,
+    ...(publicDoc.servers ? {servers: publicDoc.servers} : {}),
+    ...(publicDoc.security ? {security: publicDoc.security} : {}),
+    paths: unionMap('path collision', publicDoc.paths, adminDoc.paths),
+    components: {
+      schemas: unionMap(
+        'schema collision',
+        publicDoc.components?.schemas,
+        adminDoc.components?.schemas,
+      ),
+      parameters: unionMap(
+        'parameter collision',
+        publicDoc.components?.parameters,
+        adminDoc.components?.parameters,
+      ),
+      responses: unionMap(
+        'response collision',
+        publicDoc.components?.responses,
+        adminDoc.components?.responses,
+      ),
+      securitySchemes: unionMap(
+        'securityScheme collision',
+        publicDoc.components?.securitySchemes,
+        adminDoc.components?.securitySchemes,
+      ),
+    },
+  };
+};