feat(api-docs): generate OpenAPI components/schemas from Go structs

A new emit_jsonschema.go walks the same allow-listed structs as the zod/types/examples emitters and writes generated/schemas.ts (SCHEMAS). build-openapi mounts it under components.schemas and points each typed response obj at a $ref instead of an untyped {} blob, so Swagger renders real models and openapi-generator can emit clients.

Also add a vitest guard that safeParses every EXAMPLES entry against its generated zod schema, reviving the previously unused generated/zod.ts and catching drift between the example and schema emitters.

frontend/scripts/build-openapi.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { sections } from '../src/pages/api-docs/endpoints.ts';
 import { EXAMPLES } from '../src/generated/examples.ts';
+import { SCHEMAS } from '../src/generated/schemas.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const outPath = join(__dirname, '..', 'public', 'openapi.json');
@@ -130,12 +131,20 @@ function buildOperation(ep, tag) {
 
   const responses = {};
   let successExample = tryParseJson(ep.response);
-  if (successExample === undefined && ep.responseSchema) {
+  let objSchema = {};
+  if (ep.responseSchema) {
     const obj = EXAMPLES[ep.responseSchema];
     if (obj === undefined) {
       throw new Error(`${ep.method} ${ep.path}: responseSchema "${ep.responseSchema}" has no generated example`);
     }
-    successExample = { success: true, obj: ep.responseSchemaArray ? [obj] : obj };
+    if (SCHEMAS[ep.responseSchema] === undefined) {
+      throw new Error(`${ep.method} ${ep.path}: responseSchema "${ep.responseSchema}" has no generated schema`);
+    }
+    const ref = { $ref: `#/components/schemas/${ep.responseSchema}` };
+    objSchema = ep.responseSchemaArray ? { type: 'array', items: ref } : ref;
+    if (successExample === undefined) {
+      successExample = { success: true, obj: ep.responseSchemaArray ? [obj] : obj };
+    }
   }
   responses['200'] = {
     description: 'Successful response',
@@ -146,7 +155,7 @@ function buildOperation(ep, tag) {
           properties: {
             success: { type: 'boolean' },
             msg: { type: 'string' },
-            obj: {},
+            obj: objSchema,
           },
         },
         ...(successExample !== undefined ? { example: successExample } : {}),
@@ -200,13 +209,14 @@ function buildSpec() {
       title: '3X-UI Panel API',
       version: PANEL_VERSION,
       description:
-        'Programmatic interface to a 3X-UI panel. Authenticate either by logging in (cookie) or with an API token from Settings → Security → API Token (Bearer). All endpoints under /panel/api/* honour both modes.',
+        'Programmatic interface to a 3X-UI panel. Authenticate either by logging in (cookie) or with an API token from Settings → Security → API Token (Bearer). All endpoints under /panel/api/* honour both modes — an API token is a full-admin credential, so treat it like the panel password.',
     },
     servers: [
       { url: '/', description: 'Current panel (basePath aware)' },
     ],
     components: {
       securitySchemes: SECURITY_SCHEMES,
+      schemas: SCHEMAS,
     },
     security: [{ bearerAuth: [] }, { cookieAuth: [] }],
     tags,

frontend/src/test/generated-examples.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import type { ZodType } from 'zod';
+
+import { EXAMPLES } from '@/generated/examples';
+import * as zodSchemas from '@/generated/zod';
+
+const registry = zodSchemas as unknown as Record<string, ZodType>;
+const names = Object.keys(EXAMPLES);
+
+describe('generated response examples', () => {
+  it('has at least one example to validate', () => {
+    expect(names.length).toBeGreaterThan(0);
+  });
+
+  it('pairs every example with a generated zod schema', () => {
+    const missing = names.filter((name) => typeof registry[`${name}Schema`]?.safeParse !== 'function');
+    expect(missing).toEqual([]);
+  });
+
+  it.each(names)('EXAMPLES.%s satisfies its generated zod schema', (name) => {
+    const schema = registry[`${name}Schema`];
+    const result = schema.safeParse(EXAMPLES[name]);
+    if (!result.success) {
+      throw new Error(
+        `EXAMPLES.${name} does not match ${name}Schema:\n${JSON.stringify(result.error.issues, null, 2)}`,
+      );
+    }
+    expect(result.success).toBe(true);
+  });
+});