From caa4bb0919818668a10e5a56aedcb5a7c39ee795 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=A9my=20Munsch?= <github@jeremydev.ovh>
Date: Wed, 12 Aug 2026 17:26:17 +0200
Subject: [PATCH] feat(api): restore ping endpoint and add rate limit responses

Restores the /ping endpoint for health checks and adds
429 Too Many Requests response handling to improve API robustness.
---
 documentation/OpenApi/openapi.yaml | 40 ++++++++++++++++++------------
 routes/api.php                     |  3 +++
 routes/apiv1.php                   |  1 -
 3 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/documentation/OpenApi/openapi.yaml b/documentation/OpenApi/openapi.yaml
index ddd7aa4..c07f2b2 100644
--- a/documentation/OpenApi/openapi.yaml
+++ b/documentation/OpenApi/openapi.yaml
@@ -26,22 +26,6 @@ tags:
     description: Gestion et consultation du référentiel RH des employés.
 
 paths:
-  /ping:
-    get:
-      tags:
-        - System
-      summary: Health check (Ping)
-      description: Permet de vérifier que l'API est fonctionnelle.
-      operationId: ping
-      responses:
-        '200':
-          description: Service OK
-          content:
-            application/json:
-              schema:
-                type: string
-                example: "pong"
-
 
   /employees:
     get:
@@ -79,6 +63,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalServerError'
         '503':
@@ -111,6 +97,8 @@ paths:
           $ref: '#/components/responses/NotFound'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalServerError'
         '503':
@@ -295,6 +283,26 @@ components:
           schema:
             $ref: '#/components/schemas/ValidationErrorProblemDetails'
 
+    TooManyRequests:
+      description: Trop de requêtes envoyées dans un laps de temps donné (429 Too Many Requests).
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/ProblemDetails'
+      headers:
+        Retry-After:
+          description: Le nombre de secondes avant de pouvoir réessayer.
+          schema:
+            type: integer
+        X-RateLimit-Limit:
+          description: La limite de requêtes par minute.
+          schema:
+            type: integer
+        X-RateLimit-Remaining:
+          description: Le nombre de requêtes restantes avant blocage.
+          schema:
+            type: integer
+
     InternalServerError:
       description: Erreur interne du serveur (500 Internal Server Error).
       content:
diff --git a/routes/api.php b/routes/api.php
index 4e11106..d1b63da 100644
--- a/routes/api.php
+++ b/routes/api.php
@@ -16,6 +16,9 @@ Route::get(
     ])
 )->name('api.root');
 
+Route::get('/ping', fn () => response()->json('pong'))->name('api.ping');
+
+
 // * V1 API
 Route::prefix('v1')->name('api.v1.')->group(function () {
     require __DIR__ . '/apiv1.php';
diff --git a/routes/apiv1.php b/routes/apiv1.php
index 565fc93..f957fb6 100644
--- a/routes/apiv1.php
+++ b/routes/apiv1.php
@@ -12,7 +12,6 @@ Route::get('/', fn () => response()->json([
     'spec'    => route('api.v1.openapi'),
 ]))->name('root');
 
-Route::get('/ping', fn () => response()->json('pong'))->name('ping');
 
 Route::get('/openapi', function () {
     return response()->file(