#3 update /doc avec redocly

studoo-app · Aug 21, 2024 · 5d32c22 · 5d32c22
1 parent e144a22
commit 5d32c22
Show file tree

Hide file tree

Showing 8 changed files with 439 additions and 80 deletions.
diff --git a/app/Config/routes.yaml b/app/Config/routes.yaml
@@ -1,24 +1,24 @@
-api_init:
+initApi:
     uri: /api/init
     controller: Controller\api\InitController
     httpMethod: [GET]
 doc:
     uri: /doc
     controller: Controller\DocController
     httpMethod: [GET]
-api_stations:
+getStations:
     uri: /api/stations
     controller: Controller\api\Station\StationsController
     httpMethod: [GET]
-api_station_id:
+getStationById:
     uri: '/api/station/{id}'
     controller: Controller\api\Station\StationIdController
     httpMethod: [GET]
-api_station_id_status:
+getStationStatusById:
     uri: '/api/station/{id}/status'
     controller: Controller\api\Station\StationStatusIdController
     httpMethod: [GET]
-api_stations_status:
+getStationsStatus:
     uri: /api/stations/status
     controller: Controller\api\Status\StationsStatusController
     httpMethod: [GET]
diff --git a/app/Controller/api/InitController.php b/app/Controller/api/InitController.php
@@ -10,38 +10,91 @@
 
 class InitController implements ControllerInterface
 {
-	#[Attributes\Get(path: '/api/init')]
-	#[Attributes\Response(response: '200', description: 'Initialisation de l\'API VELIKO')]
-	public function execute(Request $request): string|null
-	{
-		header('Content-Type: application/json');
-
-        (new StationRepository())->truncateTable();
-        (new StationStatusRepository())->truncateTable();
-
-        // Fetch data on station_information
-        $apiUrlStation = 'https://velib-metropole-opendata.smovengo.cloud/opendata/Velib_Metropole/station_information.json';
-        $jsonDataStation = file_get_contents($apiUrlStation);
-        $dataStation = json_decode($jsonDataStation, true);
-
-        foreach ($dataStation["data"]["stations"] as $item) {
-            (new StationRepository())->insert($item);
-        }
+    #[Attributes\Get(
+        path: '/api/init',
+        operationId: 'initApi',
+        summary: 'initAPI',
+        description: 'Initialisation de l\'API VELIKO se fait au dédut projet. Elle permet de récupérer les données des stations et des status des stations sur API officielle de VELIB',
+    )]
+    #[Attributes\Response(
+        response: '200',
+        description: 'Initialisation de l\'API VELIKO est excutée avec succès',
+        content: new Attributes\MediaType(
+            mediaType: 'application/json',
+            examples: [
+                new Attributes\Examples(
+                    example: '/api/init',
+                    summary: '/api/init',
+                    value: [
+                        'status' => 'success',
+                        'message' => 'API VELIKO is running'
+                    ]
+                )
+            ]
+        )
+    )]
+    #[Attributes\Response(
+        response: '500',
+        description: 'Erreur interne du serveur',
+        content: new Attributes\MediaType(
+            mediaType: 'application/json',
+            examples: [
+                new Attributes\Examples(
+                    example: 'error',
+                    summary: 'Erreur interne',
+                    value: [
+                        'status' => 'error',
+                        'message' => 'Une erreur interne est survenue, veuillez regarder les logs serveur'
+                    ]
+                )
+            ]
+        )
+    )]
+    public function execute(Request $request): string|null
+    {
+        header('Content-Type: application/json');
 
-        // Fetch data on station_status
-        $apiUrlStatus = 'https://velib-metropole-opendata.smovengo.cloud/opendata/Velib_Metropole/station_status.json';
-        $jsonDataStatus = file_get_contents($apiUrlStatus);
-        $dataStatus = json_decode($jsonDataStatus, true);
+        try {
+            (new StationRepository())->truncateTable();
+            (new StationStatusRepository())->truncateTable();
 
-        foreach ($dataStatus["data"]["stations"] as $item) {
-            (new StationStatusRepository())->insert($item);
-        }
+            // Fetch data on station_information
+            $apiUrlStation = 'https://velib-metropole-opendata.smovengo.cloud/opendata/Velib_Metropole/station_information.json';
+            $jsonDataStation = file_get_contents($apiUrlStation);
+            if ($jsonDataStation === false) {
+                new \Exception("Error fetching data from API VELIB (station_information.json)");
+            }
+            $dataStation = json_decode($jsonDataStation, true);
+
+            foreach ($dataStation["data"]["stations"] as $item) {
+                (new StationRepository())->insert($item);
+            }
 
-        $listTest = [
-            "status" => "success",
-            "message" => "API VELIKO is running"
-        ];
+            // Fetch data on station_status
+            $apiUrlStatus = 'https://velib-metropole-opendata.smovengo.cloud/opendata/Velib_Metropole/station_status.json';
+            $jsonDataStatus = file_get_contents($apiUrlStatus);
+            if ($jsonDataStatus === false) {
+                new \Exception("Error fetching data from API VELIB (station_status.json)");
+            }
+            $dataStatus = json_decode($jsonDataStatus, true);
+
+            foreach ($dataStatus["data"]["stations"] as $item) {
+                (new StationStatusRepository())->insert($item);
+            }
+
+            $listTest = [
+                "status" => "success",
+                "message" => "API VELIKO is running"
+            ];
+        } catch (\Exception $e) {
+            http_response_code(500);
+            $errorResponse = [
+                "status" => "error",
+                "message" => $e->getMessage()
+            ];
+            return json_encode($errorResponse);
+        }
 
-		return json_encode($listTest);
-	}
+        return json_encode($listTest);
+    }
 }
diff --git a/app/Controller/api/Station/StationIdController.php b/app/Controller/api/Station/StationIdController.php
@@ -8,18 +8,29 @@
 
 class StationIdController implements ControllerInterface
 {
-	#[Attributes\Get(path: '/api/station/{id}')]
-    #[Attributes\Parameter(name: 'id', in: 'path', required: true, schema: new Attributes\Schema(type: 'integer'))]
-    #[Attributes\Link(
-        link: 'stations',
-        operationId: 'getStations',
-        parameters: [
-            'id' => '$response.body#/station_id'
-        ]
+	#[Attributes\Get(
+        path: '/api/station/{id}',
+        operationId: 'getStationById',
+        description: 'Récupérer les informations d une station par son ID (station_id)<br>
+        La description des champs:<br>
+        - station_id: ID de la station<br>
+        - stationCode: Code de la station<br>
+        - name: Nom de la station<br>
+        - lat: Latitude de la station<br>
+        - lon: Longitude de la station<br>
+        - capacity: Capacité de la station<br>
+        '
+    )]
+    #[Attributes\Parameter(
+        name: 'id',
+        description: 'ID de la station',
+        in: 'path',
+        required: true,
+        schema: new Attributes\Schema(type: 'integer')
     )]
 	#[Attributes\Response(
         response: '200',
-        description: 'Liste d\'une station',
+        description: 'Liste d\'une station est transmise avec succès',
         content: new Attributes\MediaType(
             mediaType: 'application/json',
             examples: [

diff --git a/app/Controller/api/Station/StationStatusIdController.php b/app/Controller/api/Station/StationStatusIdController.php
@@ -8,9 +8,62 @@
 
 class StationStatusIdController implements ControllerInterface
 {
-	#[Attributes\Get(path: '/api/station/{id}/status')]
-    #[Attributes\Parameter(name: 'id', in: 'path', required: true, schema: new Attributes\Schema(type: 'integer'))]
-	#[Attributes\Response(response: '200', description: 'Status d une station')]
+	#[Attributes\Get(
+        path: '/api/station/{id}/status',
+        operationId: 'getStationStatusById',
+        description: 'Récupérer le status d une station par son ID (station_id)<br>
+        Statut d une station dans son état actuel, celle-ci à une timestamp de dernière mise à jour (last_reported).<br>
+        La description des champs:<br>
+        - station_id: ID de la station<br>
+        - stationCode: Code de la station<br>
+        - name: Nom de la station<br>
+        - lat: Latitude de la station<br>
+        - lon: Longitude de la station<br>
+        - capacity: Capacité de la station<br>
+        - num_bikes_available: Nombre de vélos disponibles<br>
+        - num_bikes_available_types: Nombre de vélos disponibles par type (mécanique, électrique)<br>
+        - num_docks_available: Nombre de places disponibles<br>
+        - is_installed: Installation de la station (voir dans la fonction getStationsStatus)<br>
+        - is_returning: Recevoir des vélos dans la station (voir dans la fonction getStationsStatus)<br>
+        - is_renting: Location de la station (voir dans la fonction getStationsStatus)<br>
+        - last_reported: Timestamp de la dernière mise à jour de la station
+        '
+    )]
+    #[Attributes\Parameter(
+        name: 'id',
+        description: 'ID de la station',
+        in: 'path',
+        required: true,
+        schema: new Attributes\Schema(type: 'integer')
+    )]
+	#[Attributes\Response(
+        response: '200',
+        description: 'Station status est récupéré avec succès',
+        content: new Attributes\MediaType(
+            mediaType: 'application/json',
+            examples: [
+                new Attributes\Examples(
+                    example: '/api/station/17278902806/status',
+                    summary: '/api/station/17278902806/status',
+                    value: [
+                        'station_id' => 17278902806,
+                        'stationCode' => 44015,
+                        'name' => 'Rouget de L isle - Watteau',
+                        "lat" => "48.778192750803",
+                        "lon" => "2.3963020229163",
+                        "capacity" => 20,
+                        "num_bikes_available" => 4,
+                        "num_bikes_available_types" => "[{\"mechanical\":0},{\"ebike\":4}]",
+                        "num_docks_available" => 16,
+                        "is_installed" => 1,
+                        "is_returning" => 1,
+                        "is_renting" => 1,
+                        "last_reported" => 1724180445
+                    ]
+                )
+            ]
+        )
+    )]
 	public function execute(Request $request): string|null
 	{
 		header('Content-Type: application/json');

diff --git a/app/Controller/api/Station/StationsController.php b/app/Controller/api/Station/StationsController.php
@@ -8,8 +8,50 @@
 
 class StationsController implements ControllerInterface
 {
-	#[Attributes\Get(path: '/api/stations')]
-	#[Attributes\Response(response: '200', description: 'Liste des stations')]
+	#[Attributes\Get(
+        path: '/api/stations',
+        operationId: 'getStations',
+        description: 'Récupérer une liste des informations des stations<br>
+        La description des champs:<br>
+        - station_id: ID de la station<br>
+        - stationCode: Code de la station<br>
+        - name: Nom de la station<br>
+        - lat: Latitude de la station<br>
+        - lon: Longitude de la station<br>
+        - capacity: Capacité de la station<br>
+        '
+    )]
+    #[Attributes\Response(
+        response: '200',
+        description: 'Liste des informations des stations sont transmises',
+        content: new Attributes\MediaType(
+            mediaType: 'application/json',
+            examples: [
+                new Attributes\Examples(
+                    example: '/api/stations',
+                    summary: '/api/stations',
+                    value: [
+                        [
+                            'station_id' => 213688169,
+                            'stationCode' => '16107',
+                            'name' => 'Benjamin Godard - Victor Hugo',
+                            'lat' => 48.865983,
+                            'lon' => 2.275725,
+                            'capacity' => 35
+                        ],
+                        [
+                            'station_id' => 36255,
+                            'stationCode' => '9020',
+                            'name' => 'Toudouze - Clauzel',
+                            'lat' => 48.879295917335,
+                            'lon' => 2.3373600840569,
+                            'capacity' => 21
+                        ]
+                    ]
+                )
+            ]
+        )
+    )]
 	public function execute(Request $request): string|null
 	{
 		header('Content-Type: application/json');

diff --git a/app/Controller/api/Status/StationsStatusController.php b/app/Controller/api/Status/StationsStatusController.php
@@ -8,8 +8,64 @@
 
 class StationsStatusController implements ControllerInterface
 {
-	#[Attributes\Get(path: '/api/stations/status')]
-	#[Attributes\Response(response: '200', description: 'Liste des status des stations')]
+	#[Attributes\Get(
+        path: '/api/stations/status',
+        operationId: 'getStationsStatus',
+        summary: 'getStationsStatus',
+        description: 'Liste des status des stations, voici la structure de données
+        <ul>
+            <li>station_id : numéro unique d’identification de la station. Ce numéro identifie la station au sein du service Vélib’ Métropole</li>
+            <li>is_installed : variable binaire indiquant si la station est. La station a déjà été déployée (1) ou est encore en cours de déploiement (0)</li>
+            <li>is_renting : variable binaire indiquant si la station peut louer des vélos (is_renting=1 si le statut de la station est Operative)</li>
+            <li>is_returning : variable binaire indiquant si la station peut recevoir des vélos (is_renting=1 si le statut de la station est Operative)</li>
+            <li>last_reported : date de la dernière mise-à-jour</li>
+            <li>numBikesAvailable : nombre de vélos disponibles</li>
+            <li>numDocksAvailable : nombre de bornettes disponibles</li>
+            <li>num_bikes_available : nombre de vélos disponibles</li>
+            <li>num_bikes_available_types : nombre de vélos disponibles avec distinctions entre Vélib’ mécanique et électrique</li>
+        </ul>',
+    )]
+	#[Attributes\Response(
+        response: '200',
+        description: 'Liste des status des stations sont transmis',
+        content: new Attributes\MediaType(
+            mediaType: 'application/json',
+            examples: [
+                new Attributes\Examples(
+                    example: '/api/stations/status',
+                    summary: '/api/stations/status',
+                    value: [
+                        [
+                            'station_id' => '213688169',
+                            'num_bikes_available' => 7,
+                            'num_bikes_available_types' => [
+                                'mechanical' => 7,
+                                'ebike' => 0
+                            ],
+                            'num_docks_available' => 16,
+                            'is_installed' => 1,
+                            'is_returning' => 1,
+                            'is_renting' => 1,
+                            'last_reported' => 1633669200,
+                        ],
+                        [
+                            'station_id' => '17278902806',
+                            'num_bikes_available' => 4,
+                            'num_bikes_available_types' => [
+                                'mechanical' => 2,
+                                'ebike' => 2
+                            ],
+                            'num_docks_available' => 15,
+                            'is_installed' => 1,
+                            'is_returning' => 1,
+                            'is_renting' => 1,
+                            'last_reported' => 1724180746,
+                        ]
+                    ]
+                )
+            ]
+        )
+    )]
 	public function execute(Request $request): string|null
 	{
 		header('Content-Type: application/json');