all the new shiny things

src/routes/gamification.routes.ts

@@ -39,8 +39,28 @@ const awardAchievementSchema = z.object({
 // --- Public Routes ---
 
 /**
- * GET /api/achievements - Get the master list of all available achievements.
- * This is a public endpoint.
+ * @openapi
+ * /achievements:
+ *   get:
+ *     summary: Get all achievements
+ *     description: Returns the master list of all available achievements in the system. This is a public endpoint.
+ *     tags:
+ *       - Achievements
+ *     responses:
+ *       200:
+ *         description: List of all achievements
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 data:
+ *                   type: array
+ *                   items:
+ *                     $ref: '#/components/schemas/Achievement'
  */
 router.get('/', publicReadLimiter, async (req, res, next: NextFunction) => {
   try {
@@ -53,8 +73,37 @@ router.get('/', publicReadLimiter, async (req, res, next: NextFunction) => {
 });
 
 /**
- * GET /api/achievements/leaderboard - Get the top users by points.
- * This is a public endpoint.
+ * @openapi
+ * /achievements/leaderboard:
+ *   get:
+ *     summary: Get leaderboard
+ *     description: Returns the top users ranked by total points earned from achievements. This is a public endpoint.
+ *     tags:
+ *       - Achievements
+ *     parameters:
+ *       - in: query
+ *         name: limit
+ *         schema:
+ *           type: integer
+ *           minimum: 1
+ *           maximum: 50
+ *           default: 10
+ *         description: Maximum number of users to return
+ *     responses:
+ *       200:
+ *         description: Leaderboard entries
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 data:
+ *                   type: array
+ *                   items:
+ *                     $ref: '#/components/schemas/LeaderboardUser'
  */
 router.get(
   '/leaderboard',
@@ -77,8 +126,36 @@ router.get(
 // --- Authenticated User Routes ---
 
 /**
- * GET /api/achievements/me - Get all achievements for the authenticated user.
- * This is a protected endpoint.
+ * @openapi
+ * /achievements/me:
+ *   get:
+ *     summary: Get my achievements
+ *     description: Returns all achievements earned by the authenticated user.
+ *     tags:
+ *       - Achievements
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: List of user's earned achievements
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 data:
+ *                   type: array
+ *                   items:
+ *                     $ref: '#/components/schemas/UserAchievement'
+ *       401:
+ *         description: Unauthorized - JWT token missing or invalid
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
  */
 router.get(
   '/me',
@@ -108,8 +185,55 @@ router.get(
 adminGamificationRouter.use(passport.authenticate('jwt', { session: false }), isAdmin);
 
 /**
- * POST /api/achievements/award - Manually award an achievement to a user.
- * This is an admin-only endpoint.
+ * @openapi
+ * /achievements/award:
+ *   post:
+ *     summary: Award achievement to user (Admin only)
+ *     description: Manually award an achievement to a specific user. Requires admin role.
+ *     tags:
+ *       - Achievements
+ *       - Admin
+ *     security:
+ *       - bearerAuth: []
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - userId
+ *               - achievementName
+ *             properties:
+ *               userId:
+ *                 type: string
+ *                 format: uuid
+ *                 description: The user ID to award the achievement to
+ *               achievementName:
+ *                 type: string
+ *                 description: The name of the achievement to award
+ *                 example: First-Upload
+ *     responses:
+ *       200:
+ *         description: Achievement awarded successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 data:
+ *                   type: object
+ *                   properties:
+ *                     message:
+ *                       type: string
+ *                       example: Successfully awarded 'First-Upload' to user abc123.
+ *       401:
+ *         description: Unauthorized - JWT token missing or invalid
+ *       403:
+ *         description: Forbidden - User is not an admin
  */
 adminGamificationRouter.post(
   '/award',