feat: integrate Zod for schema validation in Express routes and update documentation

Author: ivictbor

adminforth/commands/createApp/templates/api.ts.hbs

@@ -1,23 +1,32 @@
-import { Express, Request, Response } from "express";
-import { IAdminForth } from "adminforth";
+import { Express, Response } from "express";
+import { IAdminForth, IAdminUserExpressRequest } from "adminforth";
+import * as z from "zod";
+
 export function initApi(app: Express, admin: IAdminForth) {
   app.get(`${admin.config.baseUrl}/api/hello/`,
 
-    // you can use data API to work with your database https://adminforth.dev/docs/tutorial/Customization/dataApi/
-    async (req: Request, res: Response) => {
-      // req.adminUser to get info about the admin users
-      const allUsers = await admin.resource("adminuser").list([]);
-      res.json({
-        message: "List of admin users from AdminForth API",
-        users: allUsers,
-      });
-    },
+    admin.express.withSchema(
+      {
+        description: "Returns example data from a custom Express API together with the current authenticated AdminForth user.",
+        response: z.object({
+          message: z.string(),
+          users: z.array(z.record(z.string(), z.unknown())),
+          adminUser: z.record(z.string(), z.unknown()),
+        }),
+      },
 
-    // you can use admin.express.authorize to get info about the current user
-    admin.express.authorize(
-      async (req: Request, res: Response) => {
-        res.json({ message: "Current adminuser from AdminForth API", adminUser: req.adminUser });
-      }
+      // you can use data API to work with your database https://adminforth.dev/docs/tutorial/Customization/dataApi/
+      // and admin.express.authorize to inject req.adminUser
+      admin.express.authorize(
+        async (req: IAdminUserExpressRequest, res: Response) => {
+          const allUsers = await admin.resource("adminuser").list([]);
+          res.json({
+            message: "Hello from AdminForth API!",
+            users: allUsers,
+            adminUser: req.adminUser,
+          });
+        }
+      )
     )
   );
 }

adminforth/commands/createApp/templates/package.json.hbs

@@ -35,7 +35,8 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.34.0",
     "adminforth": "{{adminforthVersion}}",
-    "express": "latest-4"
+    "express": "latest-4",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "typescript": "5.4.5",

adminforth/documentation/blog/2025-04-10-how-to-translate-dynamic-strings/index.md

@@ -45,7 +45,17 @@ export default {
 You might have this page and return it in your API for nuxt:
 
 ```ts
+import * as z from "zod";
+
 app.get(`${admin.config.baseUrl}/api/get_page`,
+  admin.express.withSchema(
+    {
+      description: 'Returns translated SEO metadata for the page specified by the pageUrl query parameter.',
+      response: z.object({
+        meta_title: z.string(),
+        meta_desc: z.string(),
+      }),
+    },
     async (req:any, res: Response): Promise<void> => {
       const pageUrl = req.query.pageUrl;
       if (!pageUrl) {
@@ -62,18 +72,29 @@ app.get(`${admin.config.baseUrl}/api/get_page`,
         meta_desc: page.meta_desc,
       });
     }
-  ) 
+  )
 );
 ```
 
+Install and import Zod before using this pattern: `pnpm add zod` or `npm install zod`, then `import * as z from 'zod';`. `admin.express.withSchema(...)` will convert the Zod schema to OpenAPI for you.
+
 Now you want to translate page meta title and meta description. You can do this by using `i18n` plugin for AdminForth.
 
 ```ts
 import { AdminForth } from "adminforth";
+import * as z from "zod";
 
 export const SEO_PAGE_CATEGORY = "seo_page_config";
 
 app.get(`${admin.config.baseUrl}/api/get_page`,\
+ admin.express.withSchema(
+  {
+    description: 'Returns translated SEO metadata for the page specified by the pageUrl query parameter.',
+    response: z.object({
+      meta_title: z.string(),
+      meta_desc: z.string(),
+    }),
+  },
 //diff-add
  admin.express.translatable(
     async (req:any, res: Response): Promise<void> => {
@@ -107,6 +128,7 @@ app.get(`${admin.config.baseUrl}/api/get_page`,\
         meta_desc,
       });
     }
+  )
 //diff-add
   ) 
 );

adminforth/documentation/docs/tutorial/03-Customization/06-customPages.md

@@ -310,12 +310,21 @@ Open `index.ts` file and add the following code *BEFORE* `admin.express.serve(`
 
 import type { IAdminUserExpressRequest } from 'adminforth';
 import express from 'express';
+import * as z from 'zod';
 
 ....
 
 app.get(`${ADMIN_BASE_URL}/api/dashboard/`,
-  admin.express.authorize(
-    async (req:IAdminUserExpressRequest, res: express.Response) => {
+  admin.express.withSchema(
+    {
+      description: 'Returns aggregated apartment metrics for the custom dashboard page.',
+      response: z.object({
+        apartsByDays: z.array(z.record(z.string(), z.unknown())),
+        totalAparts: z.number(),
+      }).catchall(z.unknown()),
+    },
+    admin.express.authorize(
+      async (req:IAdminUserExpressRequest, res: express.Response) => {
       const days = req.body.days || 7;
       const apartsByDays = admin.resource('aparts').dataConnector.client.prepare(
         `SELECT 
@@ -403,7 +412,8 @@ app.get(`${ADMIN_BASE_URL}/api/dashboard/`,
         totalUnlistedPrice,
         listedVsUnlistedPriceByDays,
       });
-    }
+      }
+    )
   )
 );
 
@@ -413,11 +423,15 @@ admin.discoverDatabases();
 
 ```
 
+Install and import Zod before using this pattern: `pnpm add zod` or `npm install zod`, then `import * as z from 'zod';`. `admin.express.withSchema(...)` will convert the Zod schema to OpenAPI for you.
+
 
 > ☝️ Please note that we are using `admin.express.authorize` middleware to check if the user is logged in. If you want to make this endpoint public, you can remove this middleware. If user is not logged in, the request will return 401 Unauthorized status code, and protect our statistics from leak.
 
 > ☝️ Moreover if you wrap your endpoint with `admin.express.authorize` middleware, you can access `req.adminUser` object in your endpoint to get the current user information.
 
+> ☝️ Wrapping the route with `admin.express.withSchema(...)` registers it in `/api/v1/openapi.json` and `/api-docs`. Define custom routes before `admin.express.serve(app)` so AdminForth can pick them up.
+
 > ☝️ AdminForth does not provide any facility to access data in database. You are free to use any ORM like Prisma, TypeORM, Sequelize,
 mongoose, or just use raw SQL queries against your tables.
 

adminforth/documentation/docs/tutorial/03-Customization/08-pageInjections.md

@@ -112,12 +112,21 @@ Also we have to add an Api to get percentages:
 ```ts title="./index.ts"
 import type { IAdminUserExpressRequest } from 'adminforth';
 import express from 'express';
+import * as z from 'zod';
 
 ....
 
   app.get(`${ADMIN_BASE_URL}/api/aparts-by-room-percentages/`,
-    admin.express.authorize(
-      async (req: IAdminUserExpressRequest, res: express.Response) => {
+    admin.express.withSchema(
+      {
+        description: 'Returns apartment room-count percentages for the page injection chart.',
+        response: z.array(z.object({
+          rooms: z.number(),
+          percentage: z.number(),
+        })),
+      },
+      admin.express.authorize(
+        async (req: IAdminUserExpressRequest, res: express.Response) => {
         const roomPercentages = await admin.resource('aparts').dataConnector.client.prepare(
           `SELECT 
             number_of_rooms, 
@@ -139,7 +148,8 @@ import express from 'express';
             })
           )
         );
-      }
+        }
+      )
     )
   );
 
@@ -148,8 +158,12 @@ import express from 'express';
   admin.express.serve(app)
 ```
 
+Install and import Zod before using this pattern: `pnpm add zod` or `npm install zod`, then `import * as z from 'zod';`. `admin.express.withSchema(...)` will convert the Zod schema to OpenAPI for you.
+
 > ☝️ Please note that we are using [Frontend API](/docs/api/FrontendAPI/interfaces/FrontendAPIInterface/) `adminforth.list.updateFilter({field: 'number_of_rooms', operator: 'eq', value: selectedRoomsCount});` to set filter when we are located on apartments list page
 
+> ☝️ The outer `admin.express.withSchema(...)` wrapper makes this custom Express route appear in `/api/v1/openapi.json` and `/api-docs`.
+
 Here is how it looks:
 ![alt text](<Page Injections.png>)
 

adminforth/package.json

@@ -104,7 +104,8 @@
     "rate-limiter-flexible": "^8.1.0",
     "recast": "^0.23.11",
     "ws": "^8.18.0",
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@semantic-release/exec": "^7.1.0",