From 0fce75cefa419dfd1ba77d6a9a3240485af4bdda Mon Sep 17 00:00:00 2001
From: RHM <righthandman176@proton.me>
Date: Thu, 11 Sep 2025 17:10:47 +0200
Subject: [PATCH] documentation

---
 backend/src/api.js | 195 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 195 insertions(+)

diff --git a/backend/src/api.js b/backend/src/api.js
index f634a82..9fd9320 100644
--- a/backend/src/api.js
+++ b/backend/src/api.js
@@ -16,6 +16,27 @@ router.get("/healthcheck", (req, res) => {
     res.json({ status: "ok" })
 });
 
+/**
+ * @swagger
+ * /users:
+ *   post:
+ *     summary: Create a new user
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               username:
+ *                 type: string
+ *               input_method:
+ *                 type: integer
+ *                 default: 0
+ *     responses:
+ *       201:
+ *         description: User created
+ */
 router.post("/users", async (req, res) => {
     const { username, input_method = 0 } = req.body;
 
@@ -28,16 +49,61 @@ router.post("/users", async (req, res) => {
     res.status(201).json(userRow[0]);
 });
 
+/**
+ * @swagger
+ * /games:
+ *   get:
+ *     summary: Get all current games
+ *     responses:
+ *       200:
+ *         description: List of current games
+ */
 router.get("/games", async (req, res) => {
     const [rows] = await pool.query("SELECT * FROM current_games");
     res.json(rows);
 });
 
+/**
+ * @swagger
+ * /games/{id}:
+ *   get:
+ *     summary: Get a specific game by ID
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: Game data
+ */
 router.get("/games/:id", async (req, res) => {
     const [rows] = await pool.query("SELECT * FROM current_games WHERE id = ?", [req.params.id]);
     res.json(rows[0] || null);
 });
 
+/**
+ * @swagger
+ * /games:
+ *   post:
+ *     summary: Create a new game
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               user:
+ *                 type: integer
+ *               is_local:
+ *                 type: boolean
+ *                 default: false
+ *     responses:
+ *       201:
+ *         description: Game created
+ */
 router.post("/games", async (req, res) => {
     const { user, is_local = false } = req.body;
     const conn = await pool.getConnection();
@@ -72,6 +138,30 @@ router.post("/games", async (req, res) => {
     }
 });
 
+/**
+ * @swagger
+ * /games/{id}/players:
+ *   post:
+ *     summary: Add a player to a game
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               user:
+ *                 type: integer
+ *     responses:
+ *       201:
+ *         description: Player added
+ */
 router.post("/games/:id/players", async (req, res) => {
     const { user } = req.body;
     const gameId = req.params.id;
@@ -111,6 +201,30 @@ router.post("/games/:id/players", async (req, res) => {
     }
 });
 
+/**
+ * @swagger
+ * /games/{id}/lock:
+ *   patch:
+ *     summary: Lock a game and generate turn order
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               user:
+ *                 type: integer
+ *     responses:
+ *       200:
+ *         description: Game locked with turn order
+ */
 router.patch("/games/:id/lock", async (req, res) => {
     const { user } = req.body;
     const gameId = req.params.id;
@@ -157,6 +271,21 @@ router.patch("/games/:id/lock", async (req, res) => {
     res.json({ message: "Game locked" });
 });
 
+/**
+ * @swagger
+ * /games/{id}/players:
+ *   get:
+ *     summary: Get all players in a game
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: List of players
+ */
 router.get("/games/:id/players", async (req, res) => {
     const [players] = await pool.query(
         `SELECT u.id, u.username FROM game_players gp
@@ -167,6 +296,21 @@ router.get("/games/:id/players", async (req, res) => {
     res.json(players);
 });
 
+/**
+ * @swagger
+ * /games/{id}/turns:
+ *   get:
+ *     summary: Get all turns for a game
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: List of turns
+ */
 router.get("/games/:id/turns", async (req, res) => {
     const [rows] = await pool.query(
         "SELECT * FROM turns WHERE game = ? ORDER BY round_number",
@@ -175,6 +319,42 @@ router.get("/games/:id/turns", async (req, res) => {
     res.json(rows);
 });
 
+/**
+ * @swagger
+ * /games/{id}/turns:
+ *   post:
+ *     summary: Record a new turn for a player
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               user:
+ *                 type: integer
+ *               round_number:
+ *                 type: integer
+ *               start_points:
+ *                 type: integer
+ *               first_throw:
+ *                 type: integer
+ *               second_throw:
+ *                 type: integer
+ *               third_throw:
+ *                 type: integer
+ *               end_points:
+ *                 type: integer
+ *     responses:
+ *       201:
+ *         description: Turn recorded
+ */
 router.post("/games/:id/turns", async (req, res) => {
     const { user, round_number, start_points, first_throw, second_throw, third_throw, end_points } = req.body;
     const gameId = req.params.id;
@@ -229,6 +409,21 @@ router.post("/games/:id/turns", async (req, res) => {
     }
 });
 
+/**
+ * @swagger
+ * /turns/{id}:
+ *   get:
+ *     summary: Get a specific turn by ID
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: Turn data
+ */
 router.get("/turns/:id", async (req, res) => {
     const [rows] = await pool.query("SELECT * FROM turns WHERE id = ?", [req.params.id]);
     res.json(rows[0] || null);