Swagger API documentation

backend/routes/exercise.routes.ts

@@ -1,3 +1,9 @@
+/**
+ * @swagger
+ * tags:
+ *   name: Exercises
+ *   description: API to manage the exercise progress
+ */
 import { Op } from "sequelize";
 import { Exercise } from "../models/exercises/exercise.model";
 import { ExerciseGroup } from "../models/exercises/exerciseGroup.model";
@@ -6,11 +12,28 @@ import { Request, Response, Router } from "express";
 export const exercises = Router()
 
 /**
- * Get all Exercises grouped in ExerciseGroups
+ * @swagger
+ * /exercises:
+ *   get:
+ *     summary: Download all exercises
+ *     tags: [Exercises]
+ *     responses:
+ *       200:
+ *         description: Array of all exercises
+ *         type: array
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/exercise'
+ *       500:
+ *         description: Internal server error
  */
 exercises.get("/", (req: Request, res: Response) => {
   Exercise.findAll({
-    include: [ ExerciseGroup ]
+    include: [ ExerciseGroup ],
+    attributes: {
+      exclude: [ "exerciseGroupId" ]
+    }
   })
     .then(result => {
       result.sort((a, b) => {
@@ -25,11 +48,39 @@ exercises.get("/", (req: Request, res: Response) => {
 })
 
 /**
- * Update state of an Exercise
- * 
- * @param groupNr Number of exercise group (not ID)
- * @param exerciseNr Number of exercise (not ID)
- * @param state New state boolean
+ * @swagger
+ * /exercises/{groupNr}/{exerciseNr}/{state}:
+ *   post:
+ *     summary: Update an exercise solved state
+ *     tags: [Exercises]
+ *     parameters:
+ *        - in: path
+ *          name: groupNr
+ *          schema:
+ *            type: number
+ *          required: true
+ *          description: Number of exercise group (not ID)
+ *        - in: path
+ *          name: exerciseNr
+ *          schema:
+ *            type: number
+ *          required: true
+ *          description: Number of exercise (not ID)
+ *        - in: path
+ *          name: state
+ *          schema:
+ *            type: number
+ *          required: true
+ *          description: 1 = Solved, 0 = Unsolved
+ *     responses:
+ *       200:
+ *         description: Edited exercise
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/exercise'
+ *       500:
+ *         description: Internal server error
  */
 exercises.post("/:groupNr/:exerciseNr/:state", (req: Request, res: Response) => {
   Exercise.findOne({
@@ -43,7 +94,10 @@ exercises.post("/:groupNr/:exerciseNr/:state", (req: Request, res: Response) =>
         }
       ]
     },
-    include: [ ExerciseGroup ]
+    include: [ ExerciseGroup ],
+    attributes: {
+      exclude: [ "exerciseGroupId" ]
+    }
   })
     .then(async exercise => {
       let changed = false