Add Swagger request/response examples for all DTOs and endpoints

[Menjay7]

Description

This PR enhances the API documentation by adding comprehensive Swagger request and response examples for all DTOs and endpoints. The goal is to make the API easier to understand, test, and integrate by providing consumers with realistic payload examples directly within the Swagger UI.

Motivation

The existing Swagger documentation defines schemas and endpoints but lacks concrete examples, making it difficult for developers to:

Understand the expected request payload structure
Interpret response formats and error scenarios
Quickly test APIs through Swagger UI
Reduce onboarding time and integration mistakes

Adding examples improves the developer experience and serves as living documentation for API consumers.

Changes
Added request examples for all DTOs.
Added success response examples for all endpoints.
Added validation and error response examples where applicable.
Included example values for enums, optional fields, and nested objects.
Standardized example formatting across the API documentation.
Example

Request

{
"email": "johndoe@example.com",
"firstName": "John",
"lastName": "Doe"
}

Success Response

{
"id": "usr_123456",
"email": "johndoe@example.com",
"firstName": "John",
"lastName": "Doe",
"createdAt": "2026-06-20T12:00:00Z"
}

Validation Error Response

{
"statusCode": 400,
"message": [
"email must be an email",
"firstName should not be empty"
],
"error": "Bad Request"
}
Benefits
Improves API discoverability and usability
Reduces integration errors and support requests
Accelerates developer onboarding
Provides self-documenting, executable API examples
Standardizes documentation quality across services
Testing
Verified all endpoints display request examples in Swagger UI
Verified success and error response examples render correctly
Confirmed examples match DTO validation rules and API contracts
Checked nested DTOs and enums for accurate example generation
Obtain team review and approval
Future Considerations
Automatically generate examples from DTO metadata where possible.
Add multiple examples for endpoints with different response scenarios.
Include authentication and authorization examples for protected endpoints.
Introduce documentation checks in CI to ensure Swagger examples remain synchronized with API contracts.closed #60

[nanaf6203-bit]

Requesting changes @Menjay7 — CI came back red on the Secret Scan step (Build/Lint/TS/Unit/E2E are otherwise green). For #60, please investigate the secret-scan findings on top of latest main, fix what it flagged, and push — once it clears we can merge.