From 3a82c5028da5d75192a5b496aa5208f5fc01843e Mon Sep 17 00:00:00 2001
From: Ron Rise <ron@siteworxpro.com>
Date: Mon, 1 Dec 2025 10:48:40 -0500
Subject: [PATCH] feat: add POST endpoint and security annotations to
 IndexController, implement TokenSecurity and UnauthorizedResponse

---
 src/Api.php                         |  1 +
 src/Controllers/IndexController.php |  8 ++++++--
 src/Docs/TokenSecurity.php          | 19 +++++++++++++++++++
 src/Docs/UnauthorizedResponse.php   | 26 ++++++++++++++++++++++++++
 4 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 src/Docs/TokenSecurity.php
 create mode 100644 src/Docs/UnauthorizedResponse.php

diff --git a/src/Api.php b/src/Api.php
index 99f7bdc..c3816a7 100644
--- a/src/Api.php
+++ b/src/Api.php
@@ -71,6 +71,7 @@ class Api
 
         $this->router = new Router();
         $this->router->get('/', IndexController::class . '::get');
+        $this->router->post('/', IndexController::class . '::post');
         $this->router->get('/healthz', HealthcheckController::class . '::get');
 
         $this->router->group('/.well-known', function (RouteGroup $router) {
diff --git a/src/Controllers/IndexController.php b/src/Controllers/IndexController.php
index 5fbbcda..c5d1c70 100644
--- a/src/Controllers/IndexController.php
+++ b/src/Controllers/IndexController.php
@@ -7,6 +7,8 @@ namespace Siteworxpro\App\Controllers;
 use Nyholm\Psr7\ServerRequest;
 use Psr\Http\Message\ResponseInterface;
 use Siteworxpro\App\Attributes\Guards;
+use Siteworxpro\App\Docs\TokenSecurity;
+use Siteworxpro\App\Docs\UnauthorizedResponse;
 use Siteworxpro\App\Http\JsonResponseFactory;
 use OpenApi\Attributes as OA;
 
@@ -25,7 +27,7 @@ class IndexController extends Controller
     #[Guards\Jwt]
     #[Guards\Scope(['get.index', 'status.check'])]
     #[Guards\RequireAllScopes]
-    #[OA\Get(path: '/', tags: ['Examples'])]
+    #[OA\Get(path: '/', security: [new TokenSecurity()], tags: ['Examples'])]
     #[OA\Response(
         response: '200',
         description: 'An Example Response',
@@ -34,6 +36,7 @@ class IndexController extends Controller
             new OA\Property('message', type: 'string'),
         ])
     )]
+    #[UnauthorizedResponse]
     public function get(ServerRequest $request): ResponseInterface
     {
         return JsonResponseFactory::createJsonResponse(['status_code' => 200, 'message' => 'Server is running']);
@@ -46,7 +49,7 @@ class IndexController extends Controller
      */
     #[Guards\Jwt]
     #[Guards\Scope(['post.index'])]
-    #[OA\Post(path: '/', tags: ['Examples'])]
+    #[OA\Post(path: '/', security: [new TokenSecurity()], tags: ['Examples'])]
     #[OA\Response(
         response: '200',
         description: 'An Example Response',
@@ -57,6 +60,7 @@ class IndexController extends Controller
             ]
         )
     )]
+    #[UnauthorizedResponse]
     public function post(ServerRequest $request): ResponseInterface
     {
         return JsonResponseFactory::createJsonResponse(['status_code' => 200, 'message' => 'Server is running']);
diff --git a/src/Docs/TokenSecurity.php b/src/Docs/TokenSecurity.php
new file mode 100644
index 0000000..2998de2
--- /dev/null
+++ b/src/Docs/TokenSecurity.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace Siteworxpro\App\Docs;
+
+use OpenApi\Attributes as OA;
+
+class TokenSecurity extends OA\SecurityScheme
+{
+    public function __construct()
+    {
+        parent::__construct(
+            securityScheme: 'bearerAuth',
+            type: 'http',
+            description: 'JWT based authentication using Bearer tokens.',
+            bearerFormat: 'JWT',
+            scheme: 'bearer'
+        );
+    }
+}
\ No newline at end of file
diff --git a/src/Docs/UnauthorizedResponse.php b/src/Docs/UnauthorizedResponse.php
new file mode 100644
index 0000000..742b27c
--- /dev/null
+++ b/src/Docs/UnauthorizedResponse.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace Siteworxpro\App\Docs;
+
+use OpenApi\Attributes as OA;
+
+#[\Attribute]
+class UnauthorizedResponse extends OA\Response
+{
+    public function __construct()
+    {
+        parent::__construct(
+            response: '401',
+            description: 'Unauthorized - Authentication is required and has failed or has not yet been provided.',
+            content: new OA\MediaType(
+                mediaType: 'application/json',
+                schema: new OA\Schema(
+                    properties: [
+                        new OA\Property(property: 'status_code', type: 'integer', example: 401),
+                        new OA\Property(property: 'message', type: 'string', example: 'Unauthorized'),
+                    ]
+                )
+            )
+        );
+    }
+}