Merge pull request #56 from call-0f-code/update-apidoc

Update getInterviews apidoc

Author: Harish-Naruto

src/routes/interviews.ts

@@ -5,31 +5,75 @@ import * as interviewCtrl from '../controllers/interview.controller';
 export default function interviewRouter() {
     const router = express.Router();
 
-    /**
-   * @api {get} /interviews Get all interview experiences
-   * @apiName getInterviews
-   * @apiGroup Interview
-   *
-   * @apiSuccess {Object[]} interviews List of all interview experiences
-   * @apiSuccessExample {json} Success-Response:
-   * HTTP/1.1 200 OK
-   * {
-   *   "success": true,
-   *   "data": [
-   *     {
-   *       "id": 1,
-   *       "company": "Google",
-   *       "role": "SDE Intern",
-   *       "verdict": "Selected",
-   *       "content": "It was amazing...",
-   *       "isAnonymous": false,
-   *       "memberId": "uuid-string"
-   *     }
-   *   ]
-   * }
-   *
-   * @apiError (500) InternalServerError Failed to fetch interviews from the database
-   */
+/**
+ * @api {get} /interviews Get all interview experiences (Paginated + Optional Filtering)
+ * @apiName getInterviews
+ * @apiGroup Interview
+ *
+ * @apiDescription
+ * Fetches a paginated list of all interview experiences.
+ * Filtering by verdict is optional.  
+ * 
+ * - When `verdict=All` (default) → No filtering, return *all* interview experiences.
+ * - When `verdict=Selected/Rejected/Pending` → Filter by that verdict.
+ *
+ *
+ * @apiParam {Number{1..}} [page=1] Page number (must be >= 1)
+ * @apiParam {Number{1..100}} [limit=10] Number of records per page (1–100)
+ * @apiParam {String="All","Selected","Rejected","Pending"} [verdict="All"]
+ *        If set to "All", no filtering is applied.
+ *
+ *
+ * @apiSuccess {Boolean} success Indicates success
+ * @apiSuccess {Object[]} data List of interview experiences (formatted)
+ * @apiSuccess {Number} page Current page number
+ * @apiSuccess {Number} limit Number of items per page
+ * @apiSuccess {String} verdict The applied verdict filter ("All" means no filtering)
+ * @apiSuccess {Number} total Total number of interviews matching the filter
+ * @apiSuccess {Number} totalPages Total number of pages
+ *
+ *
+ * @apiSuccessExample {json} Success-Response:
+ * HTTP/1.1 200 OK
+ * {
+ *   "success": true,
+ *   "data": [
+ *     {
+ *       "id": 45,
+ *       "company": "Google",
+ *       "role": "SDE Intern",
+ *       "verdict": "Selected",
+ *       "content": "Great experience...",
+ *       "isAnonymous": false,
+ *       "member": {
+ *         "id": "uuid-123",
+ *         "name": "John Doe",
+ *         "profilePhoto": "https://cdn.com/photo.jpg"
+ *       }
+ *     },
+ *     {
+ *       "id": 42,
+ *       "company": "Amazon",
+ *       "role": "Backend Engineer",
+ *       "verdict": "Rejected",
+ *       "content": "Challenging rounds...",
+ *       "isAnonymous": true
+ *       // member not returned because isAnonymous = true
+ *     }
+ *   ],
+ *   "page": 1,
+ *   "limit": 10,
+ *   "verdict": "All",
+ *   "total": 240,
+ *   "totalPages": 24
+ * }
+ *
+ *
+ * @apiError (400) BadRequest Invalid page, limit, or verdict
+ * @apiError (500) InternalServerError Failed to fetch interviews from the database
+ */
+
+
     router.get('/', interviewCtrl.getInterviews);