From 6c4447353e26a2e039986a6912ed46eef75a6e46 Mon Sep 17 00:00:00 2001 From: "loic.santschi" Date: Tue, 19 Dec 2023 01:11:24 +0100 Subject: [PATCH] updated the swagger doc --- .../app/Http/Controllers/VilleController.php | 64 ++++++++++++++ .../storage/api-docs/api-docs.json | 85 +++++++++++++++++++ 2 files changed, 149 insertions(+) diff --git a/backend-laravel/app/Http/Controllers/VilleController.php b/backend-laravel/app/Http/Controllers/VilleController.php index 254768c..14032b8 100644 --- a/backend-laravel/app/Http/Controllers/VilleController.php +++ b/backend-laravel/app/Http/Controllers/VilleController.php @@ -44,6 +44,44 @@ 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 @@ -51,6 +89,32 @@ public function guess($id) 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 index 34db0b1..dbbf9d4 100644 --- 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": {