Merge branch '23_swagger_comment' into dev

HE-Arc · Dec 19, 2023 · bd3109c · bd3109c
2 parents 7110805 + 6c44473
commit bd3109c
Show file tree

Hide file tree

Showing 2 changed files with 149 additions and 0 deletions.
diff --git a/backend-laravel/app/Http/Controllers/VilleController.php b/backend-laravel/app/Http/Controllers/VilleController.php
@@ -44,13 +44,77 @@ public function today()
         return $ville;
     }
 
+    /**
+     * Make a guess
+     *
+     * @OA\Get(
+     *     path="/api/ville/guess/{id}",
+     *     summary="Get a guess for a city based on the provided ID.",
+     *     description="Retrieve information about the guessed city.",
+     *     operationId="getGuess",
+     *     tags={"Ville"},
+     *     @OA\Parameter(
+     *         name="id",
+     *         in="path",
+     *         required=true,
+     *         description="The ID of the guessed city.",
+     *         @OA\Schema(type="integer")
+     *     ),
+     *
+     *     @OA\Response(
+     *          response=200,
+     *          description="Successful response",
+     *          @OA\JsonContent(
+     *              type="object",
+     *              @OA\Property(property="ville", ref="#/components/schemas/Ville"),
+     *              @OA\Property(property="canton_diff", type="boolean", description="Whether the guessed city's canton matches the current city's canton"),
+     *              @OA\Property(property="pop_diff", type="integer", description="Population comparison result"),
+     *              @OA\Property(property="lang_diff", type="string", description="Language comparison result"),
+     *              @OA\Property(property="position_diff", type="string", description="Position comparison result"),
+     *          )
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=404,
+     *         description="Ville not found"
+     *     )
+     * )
+     *
+     *  @return App\Utility\CityComparator::compareToToday
+     */
     public function guess($id)
     {
         // TODO: clean id
         $a = new CityComparator();
         return $a->compareToToday($id);
     }
 
+    /**
+     * Get all Villes.
+     *
+     * @OA\Get(
+     *     path="/api/villes",
+     *     summary="Get all cities",
+     *     description="Retrieve information about all cities.",
+     *     operationId="getAll",
+     *     tags={"Ville"},
+     *     @OA\Response(
+     *         response=200,
+     *         description="Successful response",
+     *         @OA\JsonContent(
+     *             type="array",
+     *             @OA\Items(ref="#/components/schemas/Ville")
+     *         )
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=404,
+     *         description="Ville not found"
+     *     )
+     * )
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function all()
     {
         $villes = Ville::all();

diff --git a/backend-laravel/storage/api-docs/api-docs.json b/backend-laravel/storage/api-docs/api-docs.json
@@ -33,6 +33,91 @@
                     }
                 }
             }
+        },
+        "/api/ville/guess/{id}": {
+            "get": {
+                "tags": [
+                    "Ville"
+                ],
+                "summary": "Get a guess for a city based on the provided ID.",
+                "description": "Retrieve information about the guessed city.",
+                "operationId": "getGuess",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "description": "The ID of the guessed city.",
+                        "required": true,
+                        "schema": {
+                            "type": "integer"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Successful response",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "properties": {
+                                        "ville": {
+                                            "$ref": "#/components/schemas/Ville"
+                                        },
+                                        "canton_diff": {
+                                            "description": "Whether the guessed city's canton matches the current city's canton",
+                                            "type": "boolean"
+                                        },
+                                        "pop_diff": {
+                                            "description": "Population comparison result",
+                                            "type": "integer"
+                                        },
+                                        "lang_diff": {
+                                            "description": "Language comparison result",
+                                            "type": "string"
+                                        },
+                                        "position_diff": {
+                                            "description": "Position comparison result",
+                                            "type": "string"
+                                        }
+                                    },
+                                    "type": "object"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Ville not found"
+                    }
+                }
+            }
+        },
+        "/api/villes": {
+            "get": {
+                "tags": [
+                    "Ville"
+                ],
+                "summary": "Get all cities",
+                "description": "Retrieve information about all cities.",
+                "operationId": "getAll",
+                "responses": {
+                    "200": {
+                        "description": "Successful response",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/Ville"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Ville not found"
+                    }
+                }
+            }
         }
     },
     "components": {