Merge pull request #151 from Team-VoW/feat/swagger

feat(swagger): added swagger-php to generate OpenAPI documentation and Swagger ui in dev runs to view this.

Author: kmaxii

.htaccess

@@ -1,3 +1,18 @@
+# CORS Headers - Allow requests from Swagger UI only
+<IfModule mod_headers.c>
+    # Handle preflight OPTIONS requests
+    RewriteCond %{REQUEST_METHOD} OPTIONS
+    RewriteRule ^(.*)$ $1 [R=200,L]
+    
+    # Set CORS headers only for allowed origins
+    SetEnvIf Origin "^http://localhost:8090$" CORS_ALLOW_ORIGIN=$0
+    Header always set Access-Control-Allow-Origin "%{CORS_ALLOW_ORIGIN}e" env=CORS_ALLOW_ORIGIN
+    Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS, HEAD" env=CORS_ALLOW_ORIGIN
+    Header always set Access-Control-Allow-Headers "Content-Type, Authorization, X-Requested-With" env=CORS_ALLOW_ORIGIN
+    Header always set Access-Control-Max-Age "3600" env=CORS_ALLOW_ORIGIN
+    Header always set Access-Control-Allow-Credentials "true" env=CORS_ALLOW_ORIGIN
+</IfModule>
+
 Options -Indexes
 
 RewriteEngine On

Controllers/Api/ApiController.php

@@ -4,13 +4,26 @@
 
 use VoicesOfWynn\Controllers\Controller;
 use VoicesOfWynn\Controllers\Api\ApiKey;
+use OpenApi\Attributes as OA;
 
-/**
- * Base class for all API controllers
- */
+#[OA\Info(
+    title: "Voices of Wynn API",
+    version: "1.0.0",
+    description: "API for the Voices of Wynn website and mod."
+)]
+
+#[OA\Schema(
+    schema: "Error",
+    description: "Standard error response",
+    properties: [
+        new OA\Property(property: "error", type: "string", description: "Error message"),
+        new OA\Property(property: "code", type: "integer", description: "HTTP status code")
+    ]
+)]
 abstract class ApiController extends Controller
 {
 
+
     /**
      * Controller constructor enabling output buffering and setting the Content-Type header
      * Since specific controllers don't have a constructor, this will be invoked every time a new constructor is

Controllers/Api/BootupActions/ModBootupLogger.php

@@ -2,18 +2,29 @@
 
 namespace VoicesOfWynn\Controllers\Api\BootupActions;
 
+use OpenApi\Attributes as OA;
 use VoicesOfWynn\Controllers\Api\ApiController;
 use VoicesOfWynn\Models\Api\FunFacts\FunFactGenerator;
 use VoicesOfWynn\Models\Api\MessageBroadcast\BroadcastLoader;
 use VoicesOfWynn\Models\Api\UsageAnalysis\BootupLogger;
 use VoicesOfWynn\Models\Api\VersionChecker\VersionChecker;
 
+#[OA\Tag(name: "Bootup Actions", description: "Endpoints for mod bootup.")]
 class ModBootupLogger extends ApiController
 {
 
-    /**
-     * @inheritDoc
-     */
+    #[OA\Get(
+        path: "/api/version/check",
+        summary: "Check for new version",
+        tags: ["Bootup Actions"]
+    )]
+    #[OA\Parameter(name: "id", in: "query", required: true, schema: new OA\Schema(type: "string"))]
+    #[OA\Response(
+        response: 200,
+        description: "Success"
+    )]
+    #[OA\Response(response: 400, description: "Bad request")]
+    #[OA\Response(response: 500, description: "Internal server error")]
     public function process(array $args): int
     {
         if ($_SERVER['REQUEST_METHOD'] !== 'GET') {

Controllers/Api/DiscordIntegration/DiscordIntegration.php

@@ -7,7 +7,9 @@
 use VoicesOfWynn\Models\Api\DiscordIntegration\DiscordManager;
 use VoicesOfWynn\Models\Website\DiscordRole;
 use VoicesOfWynn\Models\Website\UserException;
+use OpenApi\Attributes as OA;
 
+#[OA\Tag(name: "Discord Integration", description: "Endpoints for integrating with the Voices of Wynn Discord server.")]
 class DiscordIntegration extends ApiController
 {
     public function process(array $args): int
@@ -22,6 +24,21 @@ public function process(array $args): int
         }
     }
 
+    #[OA\Get(
+        path: "/api/discord-integration",
+        summary: "Get Discord integration data",
+        tags: ["Discord Integration"],
+        parameters: [
+            new OA\Parameter(name: "apiKey", in: "query", required: true, schema: new OA\Schema(type: "string", default: "testing")),
+            new OA\Parameter(name: "action", in: "query", required: true, schema: new OA\Schema(type: "string", enum: ["getAllUsers"]))
+        ],
+        responses: [
+            new OA\Response(response: 200, description: "Success", content: new OA\JsonContent(type: "array", items: new OA\Items(ref: "#/components/schemas/User"))),
+            new OA\Response(response: 400, description: "Bad request - invalid action"),
+            new OA\Response(response: 401, description: "Unauthorized - invalid API key"),
+            new OA\Response(response: 500, description: "Internal server error", content: new OA\JsonContent(properties: [new OA\Property(property: "error", type: "string", description: "Error message")]))
+        ]
+    )]
     /**
      * @throws UserException
      */
@@ -35,13 +52,49 @@ private function get(): int
         switch ($_GET['action']) {
             case 'getAllUsers':
                 $users = $manager->getAllUsers();
+                $decoded = json_decode($users, true);
+                
+                // Check if the response contains an error
+                if (isset($decoded['error'])) {
+                    echo $users;
+                    return 500;
+                }
+                
                 echo $users;
                 return 200;
             default:
                 return 400;
         }
     }
 
+    #[OA\Post(
+        path: "/api/discord-integration",
+        summary: "Synchronize a user",
+        tags: ["Discord Integration"],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\MediaType(
+                mediaType: "application/x-www-form-urlencoded",
+                schema: new OA\Schema(
+                    required: ["apiKey", "action", "discordId", "discordName"],
+                    properties: [
+                        new OA\Property(property: "apiKey", type: "string", default: "testing"),
+                        new OA\Property(property: "action", type: "string", enum: ["syncUser"]),
+                        new OA\Property(property: "discordId", type: "integer"),
+                        new OA\Property(property: "discordName", type: "string"),
+                        new OA\Property(property: "imgurl", type: "string"),
+                        new OA\Property(property: "name", type: "string"),
+                        new OA\Property(property: "roles", type: "string")
+                    ]
+                )
+            )
+        ),
+        responses: [
+            new OA\Response(response: 200, description: "User updated"),
+            new OA\Response(response: 201, description: "User created"),
+            new OA\Response(response: 401, description: "Unauthorized")
+        ]
+    )]
     /**
      * @throws UserException
      */