feat: enhance OpenAPI documentation generation with new schema handling and descriptions

ivictbor · ivictbor · commit 48815e17b56a · 2026-04-15T11:35:56.000Z
diff --git a/adminforth/documentation/docs/tutorial/03-Customization/06-customPages.md b/adminforth/documentation/docs/tutorial/03-Customization/06-customPages.md
@@ -303,6 +303,39 @@ Now we have to define this endpoint in the backend to make our page work:
 
 ## Defining custom API for own page and components
 
+> ☝️ Using `admin.express.withSchema(...)` is the recommended approach because it adds your route to `/api/v1/openapi.json` and `/api-docs` (Solar), performs early runtime validation for API calls, and gives agent plugins a machine-readable API contract they can use in skills. It is still optional though, and you can register plain Express routes without `withSchema(...)` if you prefer.
+
+> ☝️ If you do not want to use Zod, you can pass a plain JSON Schema object instead of a Zod schema. For example, this Zod response schema:
+>
+> ```ts
+> response: z.object({
+>   apartsByDays: z.array(z.record(z.string(), z.unknown())),
+>   totalAparts: z.number(),
+> }).catchall(z.unknown()),
+> ```
+>
+> can be written as pure JSON Schema:
+>
+> ```ts
+> response: {
+>   type: 'object',
+>   properties: {
+>     apartsByDays: {
+>       type: 'array',
+>       items: {
+>         type: 'object',
+>         additionalProperties: true,
+>       },
+>     },
+>     totalAparts: {
+>       type: 'number',
+>     },
+>   },
+>   required: ['apartsByDays', 'totalAparts'],
+>   additionalProperties: true,
+> },
+> ```
+
 
 Open `index.ts` file and add the following code *BEFORE* `admin.express.serve(` !
 
diff --git a/adminforth/modules/restApi.ts b/adminforth/modules/restApi.ts
@@ -88,6 +88,8 @@ const genericObjectSchema: AnySchemaObject = {
 };
 
 const errorResponseSchema: AnySchemaObject = {
+  title: 'AdminForthErrorResponse',
+  description: 'Standard error response returned by AdminForth endpoints.',
   type: 'object',
   required: ['error'],
   properties: {
@@ -97,20 +99,25 @@ const errorResponseSchema: AnySchemaObject = {
 };
 
 const recordIdentifierSchema: AnySchemaObject = {
+  title: 'AdminForthRecordIdentifier',
+  description: 'Record identifier accepted by AdminForth. Depending on the resource it can be a string or a number.',
   anyOf: [
     { type: 'string' },
     { type: 'number' },
   ],
 };
 
 const actionIdentifierSchema: AnySchemaObject = {
+  title: 'AdminForthActionIdentifier',
+  description: 'Action identifier accepted by AdminForth. Depending on configuration it can be a string or a number.',
   anyOf: [
     { type: 'string' },
     { type: 'number' },
   ],
 };
 
 const namedColumnSchema: AnySchemaObject = {
+  title: 'AdminForthNamedColumn',
   type: 'object',
   required: ['name'],
   properties: {
@@ -120,6 +127,7 @@ const namedColumnSchema: AnySchemaObject = {
 };
 
 const validationResultSchema: AnySchemaObject = {
+  title: 'AdminForthValidationResult',
   type: 'object',
   required: ['isValid'],
   properties: {
@@ -129,56 +137,97 @@ const validationResultSchema: AnySchemaObject = {
   additionalProperties: true,
 };
 
-const commonFilterSchemaDefs: Record<string, AnySchemaObject> = {
-  singleFilter: {
-    type: 'object',
-    properties: {
-      field: { type: 'string' },
-      operator: { type: 'string', enum: SIMPLE_FILTER_OPERATORS },
-      value: {},
-      rightField: { type: 'string' },
-      insecureRawSQL: { type: 'string' },
-      insecureRawNoSQL: {},
+const filterConditionExample = {
+  field: 'status',
+  operator: AdminForthFilterOperators.EQ,
+  value: 'active',
+};
+
+const filterGroupExample = {
+  operator: AdminForthFilterOperators.AND,
+  subFilters: [filterConditionExample],
+};
+
+const sortItemExample = {
+  field: 'createdAt',
+  direction: AdminForthSortDirections.desc,
+};
+
+const filterConditionSchema: AnySchemaObject = {
+  title: 'AdminForthFilterCondition',
+  description: 'Single field comparison used in AdminForth filtering.',
+  type: 'object',
+  properties: {
+    field: { type: 'string' },
+    operator: { type: 'string', enum: SIMPLE_FILTER_OPERATORS },
+    value: {},
+    rightField: { type: 'string' },
+    insecureRawSQL: { type: 'string' },
+    insecureRawNoSQL: {},
+  },
+  additionalProperties: true,
+  examples: [filterConditionExample],
+};
+
+const filterGroupSchema: AnySchemaObject = {
+  title: 'AdminForthFilterGroup',
+  description: 'Nested boolean filter group. Use this for AND or OR combinations of filter nodes.',
+  type: 'object',
+  required: ['operator', 'subFilters'],
+  properties: {
+    operator: {
+      type: 'string',
+      enum: [AdminForthFilterOperators.AND, AdminForthFilterOperators.OR],
+    },
+    subFilters: {
+      type: 'array',
+      items: { $ref: '#/$defs/filterNode' },
+      description: 'Nested filters evaluated with the selected operator.',
     },
-    additionalProperties: true,
   },
+  additionalProperties: true,
+  examples: [filterGroupExample],
+};
+
+const sortItemSchema: AnySchemaObject = {
+  title: 'AdminForthSortItem',
+  description: 'Single sort instruction applied in order with the rest of the list.',
+  type: 'object',
+  required: ['field', 'direction'],
+  properties: {
+    field: { type: 'string' },
+    direction: { type: 'string', enum: Object.values(AdminForthSortDirections) },
+  },
+  additionalProperties: true,
+  examples: [sortItemExample],
+};
+
+const commonFilterSchemaDefs: Record<string, AnySchemaObject> = {
+  singleFilter: filterConditionSchema,
+  filterGroup: filterGroupSchema,
   filterNode: {
+    title: 'AdminForthFilterNode',
+    description: 'Either a single filter condition or a nested filter group.',
     anyOf: [
       { $ref: '#/$defs/singleFilter' },
-      {
-        type: 'object',
-        required: ['operator', 'subFilters'],
-        properties: {
-          operator: {
-            type: 'string',
-            enum: [AdminForthFilterOperators.AND, AdminForthFilterOperators.OR],
-          },
-          subFilters: {
-            type: 'array',
-            items: { $ref: '#/$defs/filterNode' },
-          },
-        },
-        additionalProperties: true,
-      },
+      { $ref: '#/$defs/filterGroup' },
     ],
+    examples: [filterConditionExample, filterGroupExample],
   },
-  sortItem: {
-    type: 'object',
-    required: ['field', 'direction'],
-    properties: {
-      field: { type: 'string' },
-      direction: { type: 'string', enum: Object.values(AdminForthSortDirections) },
-    },
-    additionalProperties: true,
-  },
+  sortItem: sortItemSchema,
 };
 
 const commonSortSchema: AnySchemaObject = {
+  title: 'AdminForthSortList',
+  description: 'Ordered list of sort instructions.',
   type: 'array',
   items: { $ref: '#/$defs/sortItem' },
+  examples: [[sortItemExample]],
 };
 
 const commonFiltersSchema: AnySchemaObject = {
+  title: 'AdminForthFilterInput',
+  description: 'Runtime accepts either a single filter node or an array of filter nodes. The OpenAPI document normalizes this to the array form for readability.',
   oneOf: [
     {
       type: 'array',
@@ -203,9 +252,19 @@ const getResourceDataRequestSchema: AnySchemaObject = {
   required: ['resourceId', 'source', 'limit', 'offset', 'filters', 'sort'],
   properties: {
     resourceId: { type: 'string' },
-    source: { type: 'string', enum: ['show', 'list', 'edit'] },
-    limit: { type: 'integer' },
-    offset: { type: 'integer' },
+    source: {
+      type: 'string',
+      enum: ['show', 'list', 'edit'],
+      description: 'Target UI context. Show and edit requests should use direct field filters that identify a single record.',
+    },
+    limit: {
+      type: 'integer',
+      description: 'Maximum number of rows to return for the current page.',
+    },
+    offset: {
+      type: 'integer',
+      description: 'Zero-based row offset used for pagination.',
+    },
     sort: commonSortSchema,
     filters: commonFiltersSchema,
   },
@@ -287,8 +346,14 @@ const getResourceForeignDataRequestSchema: AnySchemaObject = {
   properties: {
     resourceId: { type: 'string' },
     column: { type: 'string' },
-    limit: { type: 'integer' },
-    offset: { type: 'integer' },
+    limit: {
+      type: 'integer',
+      description: 'Maximum number of dropdown options to return.',
+    },
+    offset: {
+      type: 'integer',
+      description: 'Zero-based offset used to fetch the next option page.',
+    },
     search: { type: 'string' },
     filters: commonFiltersSchema,
     sort: commonSortSchema,
diff --git a/adminforth/servers/express.ts b/adminforth/servers/express.ts
@@ -56,8 +56,13 @@ async function parseExpressCookie(req): Promise<
 
 const EXPRESS_ROUTE_SCHEMA = Symbol('adminforth.express.withSchema');
 
+type RegisteredExpressRouteSchema = IAdminForthExpressRouteSchema & {
+  request?: AnySchemaObject;
+  response?: AnySchemaObject;
+};
+
 type SchemaAnnotatedHandler = ((...args: any[]) => any) & {
-  [EXPRESS_ROUTE_SCHEMA]?: IAdminForthExpressRouteSchema;
+  [EXPRESS_ROUTE_SCHEMA]?: RegisteredExpressRouteSchema;
 };
 
 type ZodSchemaLike = {
@@ -74,7 +79,7 @@ function isZodSchemaLike(schema: unknown): schema is ZodSchemaLike {
     && ('_zod' in schema || '_def' in schema);
 }
 
-function normalizeExpressSchema(schema: unknown): AnySchemaObject | undefined {
+function normalizeExpressRuntimeSchema(schema: unknown): AnySchemaObject | undefined {
   if (!schema) {
     return undefined;
   }
@@ -335,8 +340,8 @@ class ExpressServer implements IExpressHttpServer {
     const wrapped = ((...args: any[]) => handler(...args)) as SchemaAnnotatedHandler;
     wrapped[EXPRESS_ROUTE_SCHEMA] = {
       ...schema,
-      request: normalizeExpressSchema(schema.request),
-      response: normalizeExpressSchema(schema.response),
+      request: normalizeExpressRuntimeSchema(schema.request),
+      response: normalizeExpressRuntimeSchema(schema.response),
     };
     return wrapped;
   }
@@ -444,7 +449,16 @@ class ExpressServer implements IExpressHttpServer {
   }
 
   endpoint(options) {
-    const { method='GET', path, handler, noAuth=false, description, request_schema, response_schema, responce_schema } = options;
+    const {
+      method='GET',
+      path,
+      handler,
+      noAuth=false,
+      description,
+      request_schema,
+      response_schema,
+      responce_schema,
+    } = options;
     if (!path.startsWith('/')) {
       throw new Error(`Path must start with /, got: ${path}`);
     }
diff --git a/adminforth/servers/openapi.ts b/adminforth/servers/openapi.ts
@@ -1,6 +1,7 @@
 import { createRequire } from 'module';
 import type { AnySchemaObject, ErrorObject, ValidateFunction } from 'ajv';
 import { ADMINFORTH_VERSION } from '../modules/utils.js';
+import { buildOpenApiDocument } from './openapiDocument.js';
 import {
   type IAdminForth,
   type IAdminForthApiValidationError,
@@ -113,55 +114,12 @@ class OpenApiRegistry implements IOpenApiRegistry {
   }
 
   renderOpenApiDocument(): {[key: string]: any} {
-    const paths = {} as Record<string, Record<string, unknown>>;
-
-    for (const route of this.registeredSchemas) {
-      if (!route.request_schema && !route.response_schema) {
-        continue;
-      }
-
-      if (!paths[route.path]) {
-        paths[route.path] = {};
-      }
-
-      paths[route.path][route.method] = {
-        ...(route.description ? {
-          description: route.description,
-        } : {}),
-        ...(route.request_schema ? {
-          requestBody: {
-            required: true,
-            content: {
-              'application/json': {
-                schema: route.request_schema,
-              },
-            },
-          },
-        } : {}),
-        responses: {
-          200: route.response_schema ? {
-            description: 'Successful response',
-            content: {
-              'application/json': {
-                schema: route.response_schema,
-              },
-            },
-          } : {
-            description: 'Successful response',
-          },
-        },
-      };
-    }
-
-    return {
-      openapi: '3.0.3',
-      info: {
-        title: `${this.adminforth.config.customization.brandName || 'AdminForth'} API`,
-        version: ADMINFORTH_VERSION,
-        description: 'Generated from AdminForth endpoint schemas.',
-      },
-      paths,
-    };
+    return buildOpenApiDocument({
+      title: `${this.adminforth.config.customization.brandName || 'AdminForth'} API`,
+      version: ADMINFORTH_VERSION,
+      description: 'Generated from AdminForth endpoint schemas.',
+      routes: this.registeredSchemas,
+    });
   }
 
   private findCompiledRoute(route: IRegisteredApiSchema | null): CompiledApiSchema | null {
diff --git a/adminforth/servers/openapiDocument.ts b/adminforth/servers/openapiDocument.ts
