ts-typed-api 0.2.17 → 0.2.19

package/dist/definition.d.ts

@@ -91,10 +91,13 @@ type RouteWithBody = {
     fileUpload?: FileUploadConfig;
     responses: Record<number, ZodTypeAny>;
 };
-export type RouteSchema = RouteWithoutBody | RouteWithBody;
-export type ApiDefinitionSchema = {
+export type RouteSchema = (RouteWithoutBody | RouteWithBody) & {
+    description?: string;
+};
+export type ApiDefinitionSchema<TEndpoints extends Record<string, Record<string, RouteSchema>> = Record<string, Record<string, RouteSchema>>> = {
     prefix?: string;
-    endpoints: Record<string, Record<string, RouteSchema>>;
+    sectionDescriptions?: Partial<Record<keyof TEndpoints, string>>;
+    endpoints: TEndpoints;
 };
 export declare function CreateApiDefinition<T extends ApiDefinitionSchema>(definition: T): T;
 export type ApiRouteKey<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints']> = keyof TDef['endpoints'][TDomain];

package/dist/handler.js

@@ -56,8 +56,19 @@ function preprocessQueryParams(query, querySchema) {
     return processedQuery;
 }
 // Helper function to create respond method for middleware compatibility
-function createRespondFunction(routeDefinition, responseSetter) {
+function createRespondFunction(routeDefinition, responseSetter, middlewareRes) {
     return (status, data) => {
+        // Call any registered response callbacks
+        if (middlewareRes && middlewareRes._responseCallbacks) {
+            middlewareRes._responseCallbacks.forEach((callback) => {
+                try {
+                    callback(status, data);
+                }
+                catch (error) {
+                    console.error('Error in response callback:', error);
+                }
+            });
+        }
         const responseSchema = routeDefinition.responses[status];
         if (!responseSchema) {
             console.error(`No response schema defined for status ${status}`);
@@ -305,6 +316,17 @@ middlewares) {
                 // Augment expressRes with the .respond and .setHeader methods, using TDef
                 const typedExpressRes = expressRes;
                 typedExpressRes.respond = (status, dataForResponse) => {
+                    // Call any registered response callbacks from middleware
+                    if (expressRes._responseCallbacks) {
+                        expressRes._responseCallbacks.forEach((callback) => {
+                            try {
+                                callback(status, dataForResponse);
+                            }
+                            catch (error) {
+                                console.error('Error in response callback:', error);
+                            }
+                        });
+                    }
                     // Use the passed apiDefinition object
                     const routeSchemaForHandler = apiDefinition.endpoints[currentDomain][currentRouteKey];
                     const responseSchemaForStatus = routeSchemaForHandler.responses[status];
@@ -422,11 +444,18 @@ middlewares) {
             middlewares.forEach(middleware => {
                 const wrappedMiddleware = async (req, res, next) => {
                     try {
-                        // Add respond method to res for middleware compatibility
+                        // Add respond and onFinish methods to res for middleware compatibility
                         const middlewareRes = res;
                         middlewareRes.respond = createRespondFunction(routeDefinition, (status, data) => {
                             res.status(status).json(data);
-                        });
+                        }, middlewareRes);
+                        middlewareRes.onResponse = (callback) => {
+                            // Store callback on the underlying express response so it's accessible from TypedResponse
+                            if (!res._responseCallbacks) {
+                                res._responseCallbacks = [];
+                            }
+                            res._responseCallbacks.push(callback);
+                        };
                         await middleware(req, middlewareRes, next, { domain: currentDomain, routeKey: currentRouteKey });
                     }
                     catch (error) {

package/dist/hono-cloudflare-workers.js

@@ -273,6 +273,17 @@ function registerHonoRouteHandlers(app, apiDefinition, routeHandlers, middleware
                 c.ctx = c.get('ctx') || {};
                 // Add respond method to context
                 c.respond = (status, data) => {
+                    // Call any registered response callbacks from middleware
+                    if (c._responseCallbacks) {
+                        c._responseCallbacks.forEach((callback) => {
+                            try {
+                                callback(status, data);
+                            }
+                            catch (error) {
+                                console.error('Error in response callback:', error);
+                            }
+                        });
+                    }
                     const responseSchema = routeDefinition.responses[status];
                     if (!responseSchema) {
                         console.error(`No response schema defined for status ${status} in route ${String(currentDomain)}/${String(currentRouteKey)}`);
@@ -426,9 +437,20 @@ function registerHonoRouteHandlers(app, apiDefinition, routeHandlers, middleware
                             path: c.req.path,
                             originalUrl: c.req.url
                         };
-                        // Create minimal res object with respond method for middleware compatibility
+                        // Create minimal res object with respond and onResponse methods for middleware compatibility
                         const fakeRes = {
                             respond: (status, data) => {
+                                // Call any registered response callbacks
+                                if (c._responseCallbacks) {
+                                    c._responseCallbacks.forEach((callback) => {
+                                        try {
+                                            callback(status, data);
+                                        }
+                                        catch (error) {
+                                            console.error('Error in response callback:', error);
+                                        }
+                                    });
+                                }
                                 const responseSchema = routeDefinition.responses[status];
                                 if (!responseSchema) {
                                     console.error(`No response schema defined for status ${status}`);
@@ -482,6 +504,13 @@ function registerHonoRouteHandlers(app, apiDefinition, routeHandlers, middleware
                             },
                             end: () => {
                                 // Perhaps do nothing or set response
+                            },
+                            onResponse: (callback) => {
+                                // Store callback to be called when respond() is invoked
+                                if (!c._responseCallbacks) {
+                                    c._responseCallbacks = [];
+                                }
+                                c._responseCallbacks.push(callback);
                             }
                         };
                         // Call Express-style middleware

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { ApiClient, FetchHttpClientAdapter } from './client';
 export { generateOpenApiSpec } from './openapi';
 export { generateOpenApiSpec as generateOpenApiSpec2 } from './openapi-self';
 export { CreateApiDefinition, CreateResponses, ApiDefinitionSchema } from './definition';
-export { RegisterHandlers, EndpointMiddleware, UniversalEndpointMiddleware, SimpleMiddleware, EndpointInfo } from './object-handlers';
+export { RegisterHandlers, EndpointMiddleware, UniversalEndpointMiddleware, SimpleMiddleware, EndpointInfo, MiddlewareResponse } from './object-handlers';
 export { File as UploadedFile } from './router';
 export { z as ZodSchema } from 'zod';
 export { RegisterHonoHandlers, registerHonoRouteHandlers, HonoFile, HonoFileType, honoFileSchema, HonoTypedContext, CreateTypedHonoHandlerWithContext } from './hono-cloudflare-workers';

package/dist/object-handlers.d.ts

@@ -19,6 +19,7 @@ export interface MiddlewareResponse {
     json(data: any): void;
     setHeader(name: string, value: string): void;
     end(): void;
+    onResponse(callback: (status: number, data: any) => void): void;
 }
 export type EndpointMiddlewareCtx<Ctx extends Record<string, any> = Record<string, any>, TDef extends ApiDefinitionSchema = ApiDefinitionSchema> = ((req: express.Request & {
     ctx?: Ctx;

package/dist/openapi-self.d.ts

@@ -14,6 +14,10 @@ export interface OpenAPISpec {
     components?: {
         schemas?: Record<string, SchemaObject>;
     };
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
 }
 export interface PathItem {
     get?: Operation;

package/dist/openapi-self.js

@@ -417,10 +417,12 @@ function processRoute(route, fullPath, registry, domain, anonymousTypes = false)
     const responses = createResponses(route.responses, registry, anonymousTypes);
     const operation = {
         summary: `${route.method} ${fullPath}`,
-        description: `${route.method} operation for ${fullPath}`,
         responses,
         tags: [domain]
     };
+    if (route.description) {
+        operation.description = route.description;
+    }
     if (parameters.length > 0) {
         operation.parameters = parameters;
     }
@@ -450,6 +452,7 @@ function generateOpenApiSpec(definitions, options = {}) {
     const definitionsArray = Array.isArray(definitions) ? definitions : [definitions];
     const anonymousTypes = options.anonymousTypes || false;
     const allPaths = {};
+    const allTags = [];
     // Process each definition
     for (const definition of definitionsArray) {
         const paths = processApiDefinition(definition, registry, anonymousTypes);
@@ -463,6 +466,18 @@ function generateOpenApiSpec(definitions, options = {}) {
                 allPaths[path] = pathItem;
             }
         }
+        // Collect tags from sectionDescriptions
+        if (definition.sectionDescriptions) {
+            for (const [sectionName, description] of Object.entries(definition.sectionDescriptions)) {
+                // Avoid duplicates
+                if (!allTags.find(tag => tag.name === sectionName)) {
+                    allTags.push({
+                        name: sectionName,
+                        description: description
+                    });
+                }
+            }
+        }
     }
     const spec = {
         openapi: '3.0.0',
@@ -477,6 +492,10 @@ function generateOpenApiSpec(definitions, options = {}) {
     if (options.servers && options.servers.length > 0) {
         spec.servers = options.servers;
     }
+    // Add tags if any were found
+    if (allTags.length > 0) {
+        spec.tags = allTags;
+    }
     // Add components with schemas if any were registered and not using anonymous types
     if (!anonymousTypes) {
         const schemas = registry.getSchemas();

package/dist/openapi.d.ts

@@ -1,5 +1,5 @@
-import { ApiDefinitionSchema } from './definition';
-export declare function generateOpenApiSpec(definitions: ApiDefinitionSchema | ApiDefinitionSchema[], options?: {
+import { RouteSchema } from './definition';
+export declare function generateOpenApiSpec<TEndpoints extends Record<string, Record<string, RouteSchema>>>(definitions: import('./definition').ApiDefinitionSchema<TEndpoints> | import('./definition').ApiDefinitionSchema<TEndpoints>[], options?: {
     info?: {
         title?: string;
         version?: string;

package/dist/openapi.js

@@ -47,11 +47,20 @@ function generateOpenApiSpec(definitions, options = {}) {
             },
         };
     }
+    // Collect all tags with descriptions for the OpenAPI spec
+    const allTags = [];
     // Iterate over multiple API definitions to register routes
     definitionArray.forEach((definition) => {
         Object.keys(definition.endpoints).forEach(domainNameKey => {
             // domainNameKey is a string, representing the domain like 'users', 'products'
             const domain = definition.endpoints[domainNameKey];
+            // Add tag if not already present
+            if (!allTags.find(tag => tag.name === domainNameKey)) {
+                allTags.push({
+                    name: domainNameKey,
+                    description: definition.sectionDescriptions?.[domainNameKey]
+                });
+            }
             Object.keys(domain).forEach(routeNameKey => {
                 // routeNameKey is a string, representing the route name like 'getUser', 'createProduct'
                 const route = domain[routeNameKey];
@@ -91,6 +100,7 @@ function generateOpenApiSpec(definitions, options = {}) {
                 }
                 const operation = {
                     summary: `${domainNameKey} - ${routeNameKey}`, // Use keys directly for summary
+                    description: route.description, // Use route description if provided
                     tags: [domainNameKey], // Use domainNameKey for tags
                     parameters: parameters.length > 0 ? parameters : undefined,
                     requestBody: requestBody,
@@ -103,7 +113,6 @@ function generateOpenApiSpec(definitions, options = {}) {
                     method: route.method.toLowerCase(), // Ensure method is lowercase
                     path: openApiPath,
                     ...operation,
-                    // Add description or other OpenAPI fields if available in RouteSchema
                 });
             });
         });
@@ -118,6 +127,7 @@ function generateOpenApiSpec(definitions, options = {}) {
             description: options.info?.description ?? 'Automatically generated OpenAPI specification',
         },
         servers: options.servers ?? [{ url: '/api' }], // Adjust as needed
+        tags: allTags.filter(tag => tag.description), // Only include tags that have descriptions
     });
     return openApiDocument;
 }

package/examples/advanced/definitions.ts

@@ -20,11 +20,16 @@ const ProductSchema = z.object({
 
 export const PublicApiDefinition = CreateApiDefinition({
     prefix: '/api/v1/public',
+    sectionDescriptions: {
+        auth: 'Authentication endpoints for user login and logout',
+        products: 'Product management and listing endpoints'
+    },
     endpoints: {
         auth: {
             login: {
                 method: 'POST',
                 path: '/login',
+                description: 'Authenticate a user with username and password, returns JWT token',
                 body: z.object({
                     username: z.string(),
                     password: z.string()
@@ -42,6 +47,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             logout: {
                 method: 'POST',
                 path: '/logout',
+                description: 'Log out the current user and invalidate their session',
                 responses: CreateResponses({
                     200: z.object({
                         message: z.string()
@@ -53,6 +59,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             list: {
                 method: 'GET',
                 path: '/products',
+                description: 'Retrieve a paginated list of products with optional filtering',
                 query: z.object({
                     page: z.number().int().min(1).optional().default(1),
                     limit: z.number().int().min(1).max(100).optional().default(10),

package/examples/simple/definitions.ts

@@ -2,11 +2,16 @@ import { ZodSchema as z, CreateApiDefinition, CreateResponses } from '../../src'
 
 export const PublicApiDefinition = CreateApiDefinition({
     prefix: '/api/v1/public',
+    sectionDescriptions: {
+        status: 'Health check and status endpoints',
+        common: 'Common utility endpoints'
+    },
     endpoints: {
         status: {
             probe1: {
                 method: 'GET',
                 path: '/status/probe1',
+                description: 'Advanced health check with query parameters',
                 query: z.object({
                     match: z.boolean()
                 }),
@@ -21,6 +26,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             probe2: {
                 method: 'GET',
                 path: '/status/probe2',
+                description: 'Simple health check endpoint',
                 responses: CreateResponses({
                     200: z.enum(["pong"]),
                 })
@@ -30,6 +36,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             ping: {
                 method: 'GET',
                 path: '/ping',
+                description: 'Basic ping endpoint to check if the service is alive',
                 query: z.object({
                     format: z.enum(["json", "html"]).optional()
                 }),
@@ -40,6 +47,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             customHeaders: {
                 method: 'GET',
                 path: '/custom-headers',
+                description: 'Returns information about custom headers',
                 responses: CreateResponses({
                     200: z.object({
                         message: z.string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-typed-api",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "A lightweight, type-safe RPC library for TypeScript with Zod validation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/definition.ts

@@ -184,13 +184,16 @@ type RouteWithBody = {
 };
 
 // Union type for all route schemas
-export type RouteSchema = RouteWithoutBody | RouteWithBody;
+export type RouteSchema = (RouteWithoutBody | RouteWithBody) & {
+    description?: string;
+};
 
 // Define the structure for the entire API definition object
 // Now includes an optional prefix and endpoints record
-export type ApiDefinitionSchema = {
+export type ApiDefinitionSchema<TEndpoints extends Record<string, Record<string, RouteSchema>> = Record<string, Record<string, RouteSchema>>> = {
     prefix?: string;
-    endpoints: Record<string, Record<string, RouteSchema>>;
+    sectionDescriptions?: Partial<Record<keyof TEndpoints, string>>;
+    endpoints: TEndpoints;
 };
 
 // Helper function to ensure the definition conforms to ApiDefinitionSchema

package/src/handler.ts

@@ -83,9 +83,21 @@ function preprocessQueryParams(query: any, querySchema?: z.ZodTypeAny): any {
 // Helper function to create respond method for middleware compatibility
 function createRespondFunction(
     routeDefinition: RouteSchema,
-    responseSetter: (status: number, data: any) => void
+    responseSetter: (status: number, data: any) => void,
+    middlewareRes?: any
 ) {
     return (status: number, data: any) => {
+        // Call any registered response callbacks
+        if (middlewareRes && middlewareRes._responseCallbacks) {
+            middlewareRes._responseCallbacks.forEach((callback: (status: number, data: any) => void) => {
+                try {
+                    callback(status, data);
+                } catch (error) {
+                    console.error('Error in response callback:', error);
+                }
+            });
+        }
+
         const responseSchema = routeDefinition.responses[status];
 
         if (!responseSchema) {
@@ -359,6 +371,17 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
                 const typedExpressRes = expressRes as TypedResponse<TDef, typeof currentDomain, typeof currentRouteKey>;
 
                 typedExpressRes.respond = (status, dataForResponse) => {
+                    // Call any registered response callbacks from middleware
+                    if ((expressRes as any)._responseCallbacks) {
+                        (expressRes as any)._responseCallbacks.forEach((callback: (status: number, data: any) => void) => {
+                            try {
+                                callback(status, dataForResponse);
+                            } catch (error) {
+                                console.error('Error in response callback:', error);
+                            }
+                        });
+                    }
+
                     // Use the passed apiDefinition object
                     const routeSchemaForHandler = apiDefinition.endpoints[currentDomain][currentRouteKey] as RouteSchema;
                     const responseSchemaForStatus = routeSchemaForHandler.responses[status as number];
@@ -487,11 +510,18 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
             middlewares.forEach(middleware => {
                 const wrappedMiddleware: express.RequestHandler = async (req, res, next) => {
                     try {
-                        // Add respond method to res for middleware compatibility
+                        // Add respond and onFinish methods to res for middleware compatibility
                         const middlewareRes = res as any;
                         middlewareRes.respond = createRespondFunction(routeDefinition, (status, data) => {
                             res.status(status).json(data);
-                        });
+                        }, middlewareRes);
+                        middlewareRes.onResponse = (callback: (status: number, data: any) => void) => {
+                            // Store callback on the underlying express response so it's accessible from TypedResponse
+                            if (!(res as any)._responseCallbacks) {
+                                (res as any)._responseCallbacks = [];
+                            }
+                            (res as any)._responseCallbacks.push(callback);
+                        };
                         await middleware(req, middlewareRes as MiddlewareResponse, next, { domain: currentDomain, routeKey: currentRouteKey } as any);
                     } catch (error) {
                         next(error);

package/src/hono-cloudflare-workers.ts

@@ -341,6 +341,17 @@ export function registerHonoRouteHandlers<
 
                 // Add respond method to context
                 (c as any).respond = (status: number, data: any) => {
+                    // Call any registered response callbacks from middleware
+                    if ((c as any)._responseCallbacks) {
+                        (c as any)._responseCallbacks.forEach((callback: (status: number, data: any) => void) => {
+                            try {
+                                callback(status, data);
+                            } catch (error) {
+                                console.error('Error in response callback:', error);
+                            }
+                        });
+                    }
+
                     const responseSchema = routeDefinition.responses[status];
 
                     if (!responseSchema) {
@@ -508,9 +519,20 @@ export function registerHonoRouteHandlers<
                             originalUrl: c.req.url
                         };
 
-                        // Create minimal res object with respond method for middleware compatibility
+                        // Create minimal res object with respond and onResponse methods for middleware compatibility
                         const fakeRes = {
                             respond: (status: number, data: any) => {
+                                // Call any registered response callbacks
+                                if ((c as any)._responseCallbacks) {
+                                    (c as any)._responseCallbacks.forEach((callback: (status: number, data: any) => void) => {
+                                        try {
+                                            callback(status, data);
+                                        } catch (error) {
+                                            console.error('Error in response callback:', error);
+                                        }
+                                    });
+                                }
+
                                 const responseSchema = routeDefinition.responses[status];
 
                                 if (!responseSchema) {
@@ -571,6 +593,13 @@ export function registerHonoRouteHandlers<
                             },
                             end: () => {
                                 // Perhaps do nothing or set response
+                            },
+                            onResponse: (callback: (status: number, data: any) => void) => {
+                                // Store callback to be called when respond() is invoked
+                                if (!(c as any)._responseCallbacks) {
+                                    (c as any)._responseCallbacks = [];
+                                }
+                                (c as any)._responseCallbacks.push(callback);
                             }
                         };
 

package/src/index.ts

@@ -2,7 +2,7 @@ export { ApiClient, FetchHttpClientAdapter } from './client';
 export { generateOpenApiSpec } from './openapi'
 export { generateOpenApiSpec as generateOpenApiSpec2 } from './openapi-self'
 export { CreateApiDefinition, CreateResponses, ApiDefinitionSchema } from './definition';
-export { RegisterHandlers, EndpointMiddleware, UniversalEndpointMiddleware, SimpleMiddleware, EndpointInfo } from './object-handlers';
+export { RegisterHandlers, EndpointMiddleware, UniversalEndpointMiddleware, SimpleMiddleware, EndpointInfo, MiddlewareResponse } from './object-handlers';
 export { File as UploadedFile } from './router';
 export { z as ZodSchema } from 'zod';
 

package/src/object-handlers.ts

@@ -43,6 +43,7 @@ export interface MiddlewareResponse {
     json(data: any): void;
     setHeader(name: string, value: string): void;
     end(): void;
+    onResponse(callback: (status: number, data: any) => void): void;
 }
 
 // Unified middleware type that works for both Express and Hono with context typing

package/src/openapi-self.ts

@@ -17,6 +17,10 @@ export interface OpenAPISpec {
     components?: {
         schemas?: Record<string, SchemaObject>;
     };
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
 }
 
 export interface PathItem {
@@ -558,11 +562,14 @@ function processRoute(
 
     const operation: Operation = {
         summary: `${route.method} ${fullPath}`,
-        description: `${route.method} operation for ${fullPath}`,
         responses,
         tags: [domain]
     };
 
+    if (route.description) {
+        operation.description = route.description;
+    }
+
     if (parameters.length > 0) {
         operation.parameters = parameters;
     }
@@ -609,6 +616,7 @@ export function generateOpenApiSpec(
     const anonymousTypes = options.anonymousTypes || false;
 
     const allPaths: Record<string, PathItem> = {};
+    const allTags: Array<{ name: string; description?: string }> = [];
 
     // Process each definition
     for (const definition of definitionsArray) {
@@ -623,6 +631,19 @@ export function generateOpenApiSpec(
                 allPaths[path] = pathItem;
             }
         }
+
+        // Collect tags from sectionDescriptions
+        if (definition.sectionDescriptions) {
+            for (const [sectionName, description] of Object.entries(definition.sectionDescriptions)) {
+                // Avoid duplicates
+                if (!allTags.find(tag => tag.name === sectionName)) {
+                    allTags.push({
+                        name: sectionName,
+                        description: description
+                    });
+                }
+            }
+        }
     }
 
     const spec: OpenAPISpec = {
@@ -640,6 +661,11 @@ export function generateOpenApiSpec(
         spec.servers = options.servers;
     }
 
+    // Add tags if any were found
+    if (allTags.length > 0) {
+        spec.tags = allTags;
+    }
+
     // Add components with schemas if any were registered and not using anonymous types
     if (!anonymousTypes) {
         const schemas = registry.getSchemas();

package/src/openapi.ts

@@ -1,12 +1,12 @@
-import { ApiDefinitionSchema, RouteSchema } from './definition';
+import { RouteSchema } from './definition';
 import { OpenAPIRegistry, OpenApiGeneratorV31, extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
 import { z, ZodTypeAny } from 'zod';
 
 // Extend Zod with OpenAPI capabilities
 extendZodWithOpenApi(z);
 
-export function generateOpenApiSpec(
-    definitions: ApiDefinitionSchema | ApiDefinitionSchema[],
+export function generateOpenApiSpec<TEndpoints extends Record<string, Record<string, RouteSchema>>>(
+    definitions: import('./definition').ApiDefinitionSchema<TEndpoints> | import('./definition').ApiDefinitionSchema<TEndpoints>[],
     options: {
         info?: {
             title?: string;
@@ -59,11 +59,23 @@ export function generateOpenApiSpec(
         };
     }
 
+    // Collect all tags with descriptions for the OpenAPI spec
+    const allTags: Array<{ name: string; description?: string }> = [];
+
     // Iterate over multiple API definitions to register routes
     definitionArray.forEach((definition) => {
         Object.keys(definition.endpoints).forEach(domainNameKey => {
             // domainNameKey is a string, representing the domain like 'users', 'products'
             const domain = definition.endpoints[domainNameKey];
+
+            // Add tag if not already present
+            if (!allTags.find(tag => tag.name === domainNameKey)) {
+                allTags.push({
+                    name: domainNameKey,
+                    description: definition.sectionDescriptions?.[domainNameKey]
+                });
+            }
+
             Object.keys(domain).forEach(routeNameKey => {
                 // routeNameKey is a string, representing the route name like 'getUser', 'createProduct'
                 const route: RouteSchema = domain[routeNameKey];
@@ -108,6 +120,7 @@ export function generateOpenApiSpec(
 
                 const operation = {
                     summary: `${domainNameKey} - ${routeNameKey}`, // Use keys directly for summary
+                    description: route.description, // Use route description if provided
                     tags: [domainNameKey], // Use domainNameKey for tags
                     parameters: parameters.length > 0 ? parameters : undefined,
                     requestBody: requestBody,
@@ -122,7 +135,6 @@ export function generateOpenApiSpec(
                     method: route.method.toLowerCase() as any, // Ensure method is lowercase
                     path: openApiPath,
                     ...operation,
-                    // Add description or other OpenAPI fields if available in RouteSchema
                 });
             });
         });
@@ -138,6 +150,7 @@ export function generateOpenApiSpec(
             description: options.info?.description ?? 'Automatically generated OpenAPI specification',
         },
         servers: options.servers ?? [{ url: '/api' }], // Adjust as needed
+        tags: allTags.filter(tag => tag.description), // Only include tags that have descriptions
     });
 
     return openApiDocument;

package/tests/middleware.test.ts

@@ -105,4 +105,81 @@ describe.each([
             ).rejects.toThrow('Forbidden as expected');
         });
     });
+
+    describe('Response Logging Middleware', () => {
+        let consoleSpy: jest.SpyInstance;
+
+        beforeEach(() => {
+            consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+        });
+
+        afterEach(() => {
+            consoleSpy.mockRestore();
+        });
+
+        test('should log response status without breaking functionality', async () => {
+            // The response logging middleware should not interfere with normal operation
+            const result = await client.callApi('public', 'ping', {}, {
+                200: ({ data }) => {
+                    expect(data.message).toBe('pong');
+                    return data;
+                },
+                422: ({ error }) => {
+                    throw new Error(`Validation error: ${JSON.stringify(error)}`);
+                }
+            });
+
+            expect(result.message).toBe('pong');
+
+            // Assert that console.log was called with the expected message
+            expect(consoleSpy).toHaveBeenCalledWith('[TIMING] public.ping responded with 200');
+            expect(consoleSpy).toHaveBeenCalledWith('[Test] GET /api/v1/ping - Domain: public, Route: ping');
+        });
+
+        test('should log response status for protected routes', async () => {
+            const result = await client.callApi('public', 'protected', { headers: { Authorization: 'Bearer valid-token' } }, {
+                200: ({ data }) => {
+                    expect(data.message).toBe('protected content');
+                    expect(data.user).toBe('testuser');
+                    return data;
+                },
+                401: ({ data }) => {
+                    throw new Error(`Authentication failed: ${data.error}`);
+                },
+                403: ({ data }) => {
+                    throw new Error(`Forbidden: ${data.error}`);
+                },
+                422: ({ error }) => {
+                    throw new Error(`Validation error: ${JSON.stringify(error)}`);
+                }
+            });
+
+            expect(result.user).toBe('testuser');
+
+            // Assert that console.log was called with the expected messages
+            expect(consoleSpy).toHaveBeenCalledWith('[TIMING] public.protected responded with 200');
+            expect(consoleSpy).toHaveBeenCalledWith('[Test] GET /api/v1/protected - Domain: public, Route: protected');
+        });
+
+        test('should log error status codes for auth failures', async () => {
+            await expect(
+                client.callApi('public', 'protected', {}, {
+                    200: ({ data }) => data,
+                    401: ({ data }) => {
+                        expect(data.error).toBe('No authorization header');
+                        throw new Error('Authentication failed as expected');
+                    },
+                    403: ({ data }) => {
+                        throw new Error(`Unexpected forbidden: ${data.error}`);
+                    },
+                    422: ({ error }) => {
+                        throw new Error(`Validation error: ${JSON.stringify(error)}`);
+                    }
+                })
+            ).rejects.toThrow('Authentication failed as expected');
+
+            // Assert that console.log was called with the error status
+            expect(consoleSpy).toHaveBeenCalledWith('[TIMING] public.protected responded with 401');
+        });
+    });
 });

package/tests/openapi-spec.test.ts

@@ -316,4 +316,105 @@ describe('OpenAPI Specification Generation', () => {
             }
         }
     });
+
+    test('should include section descriptions in OpenAPI tags', () => {
+        const spec = generateOpenApiSpec(PublicApiDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.tags).toBeDefined();
+        expect(Array.isArray(spec.tags)).toBe(true);
+
+        // Check that tags with descriptions are included
+        const statusTag = spec.tags?.find((tag: any) => tag.name === 'status');
+        const commonTag = spec.tags?.find((tag: any) => tag.name === 'common');
+
+        expect(statusTag).toBeDefined();
+        expect(statusTag?.description).toBe('Health check and status endpoints');
+
+        expect(commonTag).toBeDefined();
+        expect(commonTag?.description).toBe('Common utility endpoints');
+    });
+
+    test('should include route descriptions in operation descriptions', () => {
+        const spec = generateOpenApiSpec(PublicApiDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.paths).toBeDefined();
+
+        // Check specific endpoints for descriptions
+        const probe1Path = spec.paths?.['/api/v1/public/status/probe1'];
+        const pingPath = spec.paths?.['/api/v1/public/ping'];
+
+        expect(probe1Path?.get?.description).toBe('Advanced health check with query parameters');
+        expect(pingPath?.get?.description).toBe('Basic ping endpoint to check if the service is alive');
+    });
+
+    test('should handle API definitions without descriptions', () => {
+        // Create a definition without descriptions
+        const NoDescriptionDefinition = CreateApiDefinition({
+            endpoints: {
+                test: {
+                    simpleEndpoint: {
+                        method: 'GET' as const,
+                        path: '/test',
+                        responses: {
+                            200: z.object({ message: z.string() })
+                        }
+                    }
+                }
+            }
+        });
+
+        const spec = generateOpenApiSpec(NoDescriptionDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.tags).toBeUndefined(); // No tags should be generated when no descriptions
+
+        const testPath = spec.paths?.['/test'];
+        expect(testPath?.get?.description).toBeUndefined(); // No description on operation
+    });
+
+    test('should handle partial section descriptions', () => {
+        // Create a definition with only some sections having descriptions
+        const PartialDescriptionDefinition = CreateApiDefinition({
+            sectionDescriptions: {
+                section1: 'Description for section 1'
+                // section2 intentionally omitted
+            },
+            endpoints: {
+                section1: {
+                    endpoint1: {
+                        method: 'GET' as const,
+                        path: '/section1/endpoint1',
+                        responses: {
+                            200: z.object({ data: z.string() })
+                        }
+                    }
+                },
+                section2: {
+                    endpoint2: {
+                        method: 'GET' as const,
+                        path: '/section2/endpoint2',
+                        responses: {
+                            200: z.object({ data: z.string() })
+                        }
+                    }
+                }
+            }
+        });
+
+        const spec = generateOpenApiSpec(PartialDescriptionDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.tags).toBeDefined();
+        expect(spec.tags?.length).toBe(1); // Only one tag should be generated
+
+        const section1Tag = spec.tags?.find((tag: any) => tag.name === 'section1');
+        expect(section1Tag).toBeDefined();
+        expect(section1Tag?.description).toBe('Description for section 1');
+
+        // section2 should not have a tag since it has no description
+        const section2Tag = spec.tags?.find((tag: any) => tag.name === 'section2');
+        expect(section2Tag).toBeUndefined();
+    });
 });

package/tests/setup.ts

@@ -481,6 +481,14 @@ const middlewareTestHandlers = {
 // Generic middleware setup function
 function setupMiddlewareApp(app: any, isHono: boolean) {
     // Define middleware functions
+    const timingMiddleware: EndpointMiddlewareCtx<Ctx> = async (req, res, next, endpointInfo) => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        res.onResponse((status, _data) => {
+            console.log(`[TIMING] ${endpointInfo.domain}.${endpointInfo.routeKey} responded with ${status}`);
+        });
+        await next();
+    };
+
     const loggingMiddleware: EndpointMiddlewareCtx<Ctx> = async (req, res, next, endpointInfo) => {
         console.log(`[Test] ${req.method} ${req.path} - Domain: ${endpointInfo.domain}, Route: ${endpointInfo.routeKey}`);
         await next();
@@ -509,6 +517,7 @@ function setupMiddlewareApp(app: any, isHono: boolean) {
     }
 
     const middlewares = [
+        timingMiddleware,
         loggingMiddleware,
         contextMiddleware,
         authMiddleware