Feature | Extend Swagger Coverage for controller ReleasesApiController

app/Http/Controllers/Apis/ReleasesApiController.php

@@ -14,9 +14,11 @@
 
 use App\Models\Foundation\Software\Repositories\IOpenStackReleaseRepository;
 use App\ModelSerializers\SerializerUtils;
+use Illuminate\Http\Response;
 use Illuminate\Support\Facades\Log;
 use models\oauth2\IResourceServerContext;
 use ModelSerializers\SerializerRegistry;
+use OpenApi\Attributes as OA;
 
 /**
  * Class ReleasesApiController
@@ -38,10 +40,54 @@ public function __construct
         $this->repository = $repository;
     }
 
-
-    /**
-     * @return \Illuminate\Http\JsonResponse|mixed|void
-     */
+    #[OA\Get(
+        path: "/api/v1/releases/current",
+        description: "",
+        summary: 'Get Current OpenStack Release',
+        operationId: 'getCurrentRelease',
+        tags: ['Releases'],
+        security: [['releases_oauth2' => []]],
+        parameters: [
+            new OA\Parameter(
+                name: 'access_token',
+                in: 'query',
+                required: false,
+                description: 'OAuth2 access token (alternative to Authorization: Bearer)',
+                schema: new OA\Schema(type: 'string', example: 'eyJhbGciOi...'),
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                in: 'query',
+                required: false,
+                description: 'Comma-separated list of related resources to include',
+                schema: new OA\Schema(type: 'string', example: 'components,milestones')
+            ),
+            new OA\Parameter(
+                name: 'relations',
+                in: 'query',
+                required: false,
+                description: 'Relations to load eagerly',
+                schema: new OA\Schema(type: 'string', example: 'components,milestones')
+            ),
+            new OA\Parameter(
+                name: 'fields',
+                in: 'query',
+                required: false,
+                description: 'Comma-separated list of fields to return',
+                schema: new OA\Schema(type: 'string', example: 'id,name,version,status')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Current OpenStack Release',
+                content: new OA\JsonContent(ref: '#/components/schemas/OpenStackRelease')
+            ),
+            new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function getCurrent(){
         try{
             $current = $this->repository->getCurrent();

app/Swagger/schemas.php

@@ -348,4 +348,62 @@ class RSVPUpdateRequestSchema_{
 
     ]
 )]
-class RSVPAdminAddRequestSchema {}
+class RSVPAdminAddRequestSchema {}
+
+#[OA\Schema(
+    schema: 'OpenStackRelease',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'name', type: 'string', example: 'Yoga'),
+        new OA\Property(property: 'release_number', type: 'string', example: '2023.1'),
+        new OA\Property(property: 'release_date', type: 'integer', example: 1679875200),
+        new OA\Property(property: 'status', type: 'string', example: 'Current'),
+        new OA\Property(
+            property: 'components',
+            type: 'array',
+            items: new OA\Items(type: 'integer'),
+            nullable: true
+        ),
+    ]
+)]
+class OpenStackReleaseSchema {}
+
+#[OA\Schema(
+    schema: 'OpenStackComponent',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'name', type: 'string', example: 'Nova'),
+        new OA\Property(property: 'code_name', type: 'string', example: 'nova'),
+        new OA\Property(property: 'description', type: 'string', example: 'Compute service'),
+    ]
+)]
+class OpenStackComponentSchema {}
+
+#[OA\Schema(
+    schema: 'OpenStackMilestone',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'name', type: 'string', example: 'M1'),
+        new OA\Property(property: 'due_date', type: 'integer', example: 1679875200),
+        new OA\Property(property: 'description', type: 'string', example: 'First milestone'),
+    ]
+)]
+class OpenStackMilestoneSchema {}
+
+#[
+    OA\SecurityScheme(
+        type: 'oauth2',
+        securityScheme: 'releases_oauth2',
+        flows: [
+            new OA\Flow(
+                authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+                tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+                flow: 'authorizationCode',
+                scopes: [],
+            ),
+        ],
+    )
+]
+class ReleasesAuthSchema{}