feat: Enhance users API with detailed response schemas and OpenAPI documentation

- Added response schemas for user operations including success and error responses.
- Updated existing routes to include OpenAPI schema definitions for better documentation.
- Implemented user statistics retrieval and role-based user listing with appropriate schemas.
- Improved error handling and response consistency across user-related endpoints.

Author: Lasim

.gitignore

@@ -67,3 +67,4 @@ services/backend/tests/e2e/test-data/*.db
 ._*.json
 cookies.txt
 cookiejar.txt
+services/backend/tests/e2e/.test-context.json

package-lock.json

@@ -4,7 +4,7 @@ This document explains how to generate and use the OpenAPI specification for the
 
 ## Overview
 
-The DeployStack Backend uses Fastify with Swagger plugins to automatically generate OpenAPI 3.0 specifications from route definitions. This provides:
+The DeployStack Backend uses Fastify with Swagger plugins to automatically generate OpenAPI 3.0 specifications. Route schemas are defined using [Zod](https://zod.dev/) for type safety and expressiveness, and then converted to JSON Schema using the [zod-to-json-schema](https://www.npmjs.com/package/zod-to-json-schema) library. This provides:
 
 - **Interactive Documentation**: Swagger UI interface for testing APIs
 - **Postman Integration**: JSON/YAML specs that can be imported into Postman
@@ -86,31 +86,145 @@ When the server is running (`npm run dev`), you can access:
 
 ## Adding Documentation to Routes
 
-To add OpenAPI documentation to your routes, include a schema object:
+To add OpenAPI documentation to your routes, define your request body and response schemas using Zod. Then, use the `zodToJsonSchema` utility to convert these Zod schemas into the JSON Schema format expected by Fastify.
+
+Make sure you have `zod` and `zod-to-json-schema` installed in your backend service.
+
+### Recommended Approach: Automatic Validation with Zod
+
+The power of Zod lies in providing **automatic validation** through Fastify's schema system. This approach eliminates manual validation and leverages Zod's full validation capabilities.
 
 ```typescript
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+// 1. Define your Zod schemas for request body, responses, etc.
+const myRequestBodySchema = z.object({
+  name: z.string().min(3).describe("The name of the item (min 3 chars)"),
+  count: z.number().positive().describe("How many items (must be positive)"),
+  type: z.enum(['mysql', 'sqlite']).describe("Database engine type")
+});
+
+const mySuccessResponseSchema = z.object({
+  success: z.boolean().describe("Indicates if the operation was successful"),
+  itemId: z.string().uuid().describe("The UUID of the created/affected item"),
+  message: z.string().optional().describe("Optional success message")
+});
+
+const myErrorResponseSchema = z.object({
+  success: z.boolean().default(false).describe("Indicates failure"),
+  error: z.string().describe("Error message detailing what went wrong")
+});
+
+// 2. Construct the Fastify route schema using zodToJsonSchema
 const routeSchema = {
-  tags: ['Category'],
-  summary: 'Brief description',
-  description: 'Detailed description of what this endpoint does',
-  security: [{ cookieAuth: [] }], // If authentication required
+  tags: ['Category'], // Your API category
+  summary: 'Brief description of your endpoint',
+  description: 'Detailed description of what this endpoint does, its parameters, and expected outcomes.',
+  security: [{ cookieAuth: [] }], // Include if authentication is required
+  body: zodToJsonSchema(myRequestBodySchema, { 
+    $refStrategy: 'none', // Keeps definitions inline, often simpler for Fastify
+    target: 'openApi3'   // Ensures compatibility with OpenAPI 3.0
+  }),
   response: {
-    200: {
-      type: 'object',
-      properties: {
-        success: { type: 'boolean' },
-        message: { type: 'string' }
-      },
-      required: ['success', 'message']
-    }
+    200: zodToJsonSchema(mySuccessResponseSchema.describe("Successful operation"), { 
+      $refStrategy: 'none', 
+      target: 'openApi3' 
+    }),
+    400: zodToJsonSchema(myErrorResponseSchema.describe("Bad Request - Invalid input"), { 
+      $refStrategy: 'none', 
+      target: 'openApi3' 
+    }),
+    // Define other responses (e.g., 401, 403, 404, 500) similarly
   }
 };
 
-fastify.post('/your-route', { schema: routeSchema }, async (request, reply) => {
-  // Your route handler
-});
+// 3. Use the schema in your Fastify route definition with proper TypeScript typing
+interface RequestBody {
+  name: string;
+  count: number;
+  type: 'mysql' | 'sqlite';
+}
+
+fastify.post<{ Body: RequestBody }>(
+  '/your-route', 
+  { schema: routeSchema }, 
+  async (request, reply) => {
+    // ✅ Fastify has already validated request.body using our Zod schema
+    // ✅ If we reach here, request.body is guaranteed to be valid
+    // ✅ No manual validation needed!
+    
+    const { name, count, type } = request.body; // Fully typed and validated
+    
+    // Your route handler logic here
+    return reply.status(200).send({ 
+      success: true, 
+      itemId: 'some-uuid-v4-here', 
+      message: `Item ${name} processed successfully with ${count} items using ${type}.` 
+    });
+  }
+);
 ```
 
+### Key Benefits of This Approach
+
+1. **Single Source of Truth**: Zod schemas define both validation AND documentation
+2. **Automatic Validation**: Fastify automatically validates requests before your handler runs
+3. **No Manual Validation**: Remove all manual `zod.parse()` calls and field checks
+4. **Better Error Messages**: Fastify provides detailed validation errors automatically
+5. **Type Safety**: Handlers receive properly typed, validated data
+6. **Cleaner Code**: No redundant validation logic in handlers
+
+### What NOT to Do (Anti-patterns)
+
+❌ **Don't do manual validation in handlers:**
+```typescript
+// BAD: Manual validation (redundant)
+const parsedBody = myRequestBodySchema.safeParse(request.body);
+if (!parsedBody.success) {
+  return reply.status(400).send({ error: 'Invalid request body' });
+}
+
+// BAD: Manual field checks (redundant)
+if (!request.body.name || !request.body.count) {
+  return reply.status(400).send({ error: 'Required fields missing' });
+}
+
+// BAD: Manual enum validation (redundant)
+if (request.body.type !== 'mysql' && request.body.type !== 'sqlite') {
+  return reply.status(400).send({ error: 'Invalid database type' });
+}
+```
+
+✅ **Do trust Fastify's automatic validation:**
+```typescript
+// GOOD: Trust the validation - if handler runs, data is valid
+const { name, count, type } = request.body; // Already validated by Fastify
+```
+
+### Validation Flow
+
+The validation chain works as follows:
+
+**Zod Schema → JSON Schema → Fastify Validation → Handler**
+
+1. **Zod Schema**: Define validation rules using Zod
+2. **JSON Schema**: Convert to OpenAPI format using `zodToJsonSchema()`
+3. **Fastify Validation**: Fastify automatically validates incoming requests
+4. **Handler**: Receives validated, typed data
+
+If validation fails, Fastify automatically returns a 400 error **before** your handler runs.
+
+### Real-World Examples
+
+See these files for complete examples of proper Zod validation:
+- `src/routes/db/setup.ts` - Database setup with enum validation
+- `src/routes/db/status.ts` - Simple GET endpoint with response schemas
+- `src/routes/auth/loginEmail.ts` - Login with required string fields
+- `src/routes/auth/registerEmail.ts` - Registration with complex validation rules
+
+**Note**: Older examples in this document (like the "Logout Route Documentation" below) might still show manually crafted JSON schemas. The recommended approach is now to use Zod with automatic Fastify validation as shown above.
+
 ## Example: Logout Route Documentation
 
 The logout route (`/api/auth/logout`) demonstrates proper documentation:

services/backend/API_DOCUMENTATION.md

@@ -692,6 +692,16 @@ When the server starts:
 | `github.oauth.callback_url` | `'http://localhost:3000/api/auth/github/callback'` | ❌ | ❌ | OAuth callback URL |
 | `github.oauth.scope` | `'user:email'` | ❌ | ❌ | OAuth requested scopes |
 
+#### Global Settings (Group ID: `global`)
+
+| Key | Default | Required | Encrypted | Description |
+|-----|---------|----------|-----------|-------------|
+| `global.page_url` | `'http://localhost:5173'` | ❌ | ❌ | Base URL for the application frontend |
+| `global.send_mail` | `'false'` | ❌ | ❌ | Enable or disable email sending functionality |
+| `global.enable_login` | `'true'` | ❌ | ❌ | Enable or disable all login functionality |
+| `global.enable_email_registration` | `'true'` | ❌ | ❌ | Enable or disable email registration |
+| `global.enable_swagger_docs` | `'true'` | ❌ | ❌ | Enable or disable Swagger API documentation endpoint (/documentation) |
+
 ### Helper Methods
 
 The system provides helper methods for retrieving complete configurations: