Feat/swagger UI v2

.eslintrc.json

@@ -32,7 +32,7 @@
           ["^"], // <-- to match regular imports (not starting with a special character)
 
           // Your internal path aliases
-          ["^(@modules|@common|@src)(/.*|$)"],
+          ["^(@modules|@common|@src|@api-docs)(/.*|$)"],
 
           // Relative imports
           ["^\\.\\.(?!/?$)", "^\\.\\./?$"],

.prettierignore

@@ -1,4 +1,5 @@
 node_modules
 build
 coverage
-.eslintcache
+.eslintcache
+tsconfig.json

.prettierrc

@@ -3,5 +3,13 @@
   "tabWidth": 2,
   "printWidth": 120,
   "singleQuote": true,
-  "semi": true
+  "semi": true,
+  "overrides": [
+    {
+      "files": "*.json",
+      "options": {
+        "parser": "json"
+      }
+    }
+  ]
 }

jest.config.js

@@ -10,7 +10,6 @@ module.exports = {
   moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, {
     prefix: '<rootDir>/',
   }),
-
   transform: {
     '^.+\\.(ts|tsx)$': 'ts-jest',
   },

package.json

@@ -56,10 +56,7 @@
     "typescript": "^5.3.3"
   },
   "lint-staged": {
-    "**/*.{ts,js,json}": [
-      "npm run lint",
-      "npm run format"
-    ],
+    "**/*.{ts,js,json}": ["npm run lint", "npm run format"],
     "src/**/*.{ts,js,json}": "npm run format",
     "tests/**/*.{ts,js,json}": "npm run format"
   },

src/common/middleware/openAPIDocument.ts → src/api-docs/openAPIDocumentGenerator.ts

@@ -1,7 +1,7 @@
 import { OpenApiGeneratorV3, OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
 
-import { healthCheckRegistry } from '@modules/healthCheck/healthCheckRegistry';
-import { userRegistry } from '@modules/user/userRegistry';
+import { healthCheckRegistry } from '@modules/healthCheck/healthCheckRouter';
+import { userRegistry } from '@modules/user/userRouter';
 
 export function generateOpenAPIDocument() {
   const registry = new OpenAPIRegistry([healthCheckRegistry, userRegistry]);

src/api-docs/openAPIResponseBuilders.ts

@@ -0,0 +1,41 @@
+import { StatusCodes } from 'http-status-codes';
+import { z } from 'zod';
+
+import { ServiceResponseSchema } from '@common/models/serviceResponse';
+
+export function createApiResponse(schema: z.ZodTypeAny, description: string, statusCode = StatusCodes.OK) {
+  return {
+    [statusCode]: {
+      description,
+      content: {
+        'application/json': {
+          schema: ServiceResponseSchema(schema),
+        },
+      },
+    },
+  };
+}
+
+// Use if you want multiple responses for a single endpoint
+
+// import { ResponseConfig } from '@asteasolutions/zod-to-openapi';
+// import { ApiResponseConfig } from '@common/models/openAPIResponseConfig';
+// export type ApiResponseConfig = {
+//   schema: z.ZodTypeAny;
+//   description: string;
+//   statusCode: StatusCodes;
+// };
+// export function createApiResponses(configs: ApiResponseConfig[]) {
+//   const responses: { [key: string]: ResponseConfig } = {};
+//   configs.forEach(({ schema, description, statusCode }) => {
+//     responses[statusCode] = {
+//       description,
+//       content: {
+//         'application/json': {
+//           schema: ServiceResponseSchema(schema),
+//         },
+//       },
+//     };
+//   });
+//   return responses;
+// }

src/modules/healthCheck/healthCheckRouter.ts

@@ -1,12 +1,24 @@
+import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
 import express, { Request, Response, Router } from 'express';
 import { StatusCodes } from 'http-status-codes';
+import { z } from 'zod';
 
+import { createApiResponse } from '@api-docs/openAPIResponseBuilders';
 import { ResponseStatus, ServiceResponse } from '@common/models/serviceResponse';
 import { handleServiceResponse } from '@common/utils/httpHandlers';
 
+export const healthCheckRegistry = new OpenAPIRegistry();
+
 export const healthCheckRouter: Router = (() => {
   const router = express.Router();
 
+  healthCheckRegistry.registerPath({
+    method: 'get',
+    path: '/health-check',
+    tags: ['Health Check'],
+    responses: createApiResponse(z.null(), 'Success'),
+  });
+
   router.get('/', (_req: Request, res: Response) => {
     const serviceResponse = new ServiceResponse(ResponseStatus.Success, 'Service is healthy', null, StatusCodes.OK);
     handleServiceResponse(serviceResponse, res);

src/modules/user/userModel.ts

@@ -6,20 +6,16 @@ import { commonValidations } from '@common/utils/commonValidation';
 extendZodWithOpenApi(z);
 
 export type User = z.infer<typeof UserSchema>;
-export const UserSchema = z
-  .object({
-    id: z.number(),
-    name: z.string(),
-    email: z.string().email(),
-    age: z.number(),
-    createdAt: z.date(),
-    updatedAt: z.date(),
-  })
-  .openapi('User');
+export const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+  age: z.number(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
 
 // Schema for 'GET users/:id' endpoint
-export const GetUserSchema = z
-  .object({
-    params: z.object({ id: commonValidations.id }),
-  })
-  .openapi('GetUser');
+export const GetUserSchema = z.object({
+  params: z.object({ id: commonValidations.id }),
+});

src/modules/user/userRouter.ts

@@ -1,18 +1,41 @@
+import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
 import express, { Request, Response, Router } from 'express';
+import { z } from 'zod';
 
+import { createApiResponse } from '@api-docs/openAPIResponseBuilders';
 import { handleServiceResponse, validateRequest } from '@common/utils/httpHandlers';
 import { userService } from '@modules/user/userService';
 
-import { GetUserSchema } from './userModel';
+import { GetUserSchema, UserSchema } from './userModel';
+
+export const userRegistry = new OpenAPIRegistry();
+
+userRegistry.register('User', UserSchema);
+userRegistry.register('GetUser', GetUserSchema);
 
 export const userRouter: Router = (() => {
   const router = express.Router();
 
+  userRegistry.registerPath({
+    method: 'get',
+    path: '/users',
+    tags: ['User'],
+    responses: createApiResponse(z.array(UserSchema), 'Success'),
+  });
+
   router.get('/', async (_req: Request, res: Response) => {
     const serviceResponse = await userService.findAll();
     handleServiceResponse(serviceResponse, res);
   });
 
+  userRegistry.registerPath({
+    method: 'get',
+    path: '/users/{id}',
+    tags: ['User'],
+    request: { params: GetUserSchema.shape.params },
+    responses: createApiResponse(UserSchema, 'Success'),
+  });
+
   router.get('/:id', validateRequest(GetUserSchema), async (req: Request, res: Response) => {
     const id = parseInt(req.params.id as string, 10);
     const serviceResponse = await userService.findById(id);

src/server.ts

@@ -6,8 +6,8 @@ import path from 'path';
 import { pino } from 'pino';
 import swaggerUi from 'swagger-ui-express';
 
+import { generateOpenAPIDocument } from '@api-docs/openAPIDocumentGenerator';
 import errorHandler from '@common/middleware/errorHandler';
-import { generateOpenAPIDocument } from '@common/middleware/openAPIDocument';
 import rateLimiter from '@common/middleware/rateLimiter';
 import requestLogger from '@common/middleware/requestLogger';
 import { getCorsOrigin } from '@common/utils/envConfig';

tsconfig.json

@@ -4,9 +4,10 @@
     "module": "CommonJS",
     "baseUrl": ".",
     "paths": {
-      "@modules/*": ["./src/modules/*"],
-      "@common/*": ["./src/common/*"],
-      "@src/*": ["./src/*"]
+      "@api-docs/*": ["src/api-docs/*"],
+      "@common/*": ["src/common/*"],
+      "@modules/*": ["src/modules/*"],
+      "@src/*": ["src/*"]
     },
     "moduleResolution": "Node",
     "outDir": "build",