feat: add POST endpoint and security annotations to IndexController, implement TokenSecurity and UnauthorizedResponse

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) {

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']);

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'
+        );
+    }
+}

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'),
+                    ]
+                )
+            )
+        );
+    }
+}