Feature | Extend Swagger Coverage for controller AppliancesApiController

app/Http/Controllers/Apis/Marketplace/AppliancesApiController.php

@@ -1,4 +1,7 @@
-<?php namespace App\Http\Controllers;
+<?php
+
+namespace App\Http\Controllers;
+
 /**
  * Copyright 2017 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,7 +15,9 @@
  * limitations under the License.
  **/
 use App\Models\Foundation\Marketplace\IApplianceRepository;
+use Illuminate\Http\Response;
 use models\oauth2\IResourceServerContext;
+use OpenApi\Attributes as OA;
 
 /**
  * Class AppliancesApiController
@@ -24,14 +29,87 @@ final class AppliancesApiController extends AbstractCompanyServiceApiController
     /**
      * AppliancesApiController constructor.
      * @param IApplianceRepository $repository
+     * @param IResourceServerContext $resource_server_context
      */
     public function __construct(IApplianceRepository $repository, IResourceServerContext $resource_server_context)
     {
         parent::__construct($repository, $resource_server_context);
     }
 
+    #[OA\Get(
+        path: "/api/public/v1/marketplace/appliances",
+        description: "Get all marketplace appliances (OpenStack implementations)",
+        summary: 'Get all appliances',
+        operationId: 'getAllAppliances',
+        tags: ['Appliances', 'Marketplace'],
+        parameters: [
+            new OA\Parameter(
+                name: 'page',
+                in: 'query',
+                required: false,
+                description: 'Page number for pagination',
+                schema: new OA\Schema(type: 'integer', example: 1)
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                in: 'query',
+                required: false,
+                description: 'Items per page',
+                schema: new OA\Schema(type: 'integer', example: 10, maximum: 100)
+            ),
+            new OA\Parameter(
+                name: 'filter[]',
+                in: 'query',
+                required: false,
+                description: 'Filter expressions in the format field<op>value. Available fields: name, company. Operators: =@, ==, @@.',
+                style: 'form',
+                explode: true,
+                schema: new OA\Schema(
+                    type: 'array',
+                    items: new OA\Items(type: 'string', example: 'name@@openstack')
+                )
+            ),
+            new OA\Parameter(
+                name: 'order',
+                in: 'query',
+                required: false,
+                description: 'Order by field(s)',
+                schema: new OA\Schema(type: 'string', example: 'name,-id')
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                in: 'query',
+                required: false,
+                description: 'Comma-separated list of related resources to include. Available relations: company, type, capabilities, guests, hypervisors, supported_regions',
+                schema: new OA\Schema(type: 'string', example: 'company,type')
+            ),
+            new OA\Parameter(
+                name: 'relations',
+                in: 'query',
+                required: false,
+                description: 'Relations to load eagerly',
+                schema: new OA\Schema(type: 'string', example: 'company,type')
+            ),
+            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,company.name')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Success - Returns paginated list of appliances',
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedAppliancesResponse')
+            ),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error")
+        ]
+    )]
     public function getAll()
     {
         return parent::getAll();
     }
-}
+}

app/Models/Foundation/Marketplace/CompanyService.php

@@ -225,4 +225,4 @@ public function getResources()
     {
         return $this->resources->toArray();
     }
-}
+}

app/Swagger/MarketplaceSchemas.php

@@ -85,3 +85,56 @@ class PaginatedMarketplaceDistributionResponseSchema
 class PaginatedPublicOrPrivateCloudsResponseSchema
 {
 }
+
+#[OA\Schema(
+    schema: 'MarketplaceAppliancesResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'class_name', type: 'string', example: 'Appliance'),
+        new OA\Property(property: 'name', type: 'string', example: 'OpenStack Private Cloud Appliance'),
+        new OA\Property(property: 'overview', type: 'string', example: 'Complete OpenStack solution'),
+        new OA\Property(property: 'call_2_action_url', type: 'string', example: 'https://example.com/contact'),
+        new OA\Property(property: 'slug', type: 'string', example: 'openstack-appliance'),
+        new OA\Property(property: 'is_compatible_with_storage', type: 'boolean', example: true),
+        new OA\Property(property: 'is_compatible_with_compute', type: 'boolean', example: true),
+        new OA\Property(property: 'is_compatible_with_federated_identity', type: 'boolean', example: false),
+        new OA\Property(property: 'is_compatible_with_platform', type: 'boolean', example: true),
+        new OA\Property(property: 'is_openstack_powered', type: 'boolean', example: true),
+        new OA\Property(property: 'is_openstack_tested', type: 'boolean', example: true),
+        new OA\Property(property: 'openstack_tested_info', type: 'string', example: 'Tested with OpenStack Yoga'),
+        new OA\Property(property: 'company_id', type: 'integer', example: 41, description: 'ID of the company that provides this appliance, visible only when is not expanded'),
+        new OA\Property(property: 'company', type: 'Company', description: 'Company that provides this appliance, visible only when expanded'),
+        new OA\Property(property: 'type_id', type: 'integer', example: 13, description: 'ID of the type of this appliance'),
+        new OA\Property(property: 'type', type: 'MarketPlaceType', description: 'Type of this appliance, visible only when expanded'),
+        new OA\Property(property: 'types', type: 'array', items: new OA\Items(type: 'MarketPlaceType'), description: 'Regional support of this appliance, visible only when requested as relation'),
+        new OA\Property(property: 'reviews', type: 'array', items: new OA\Items(type: 'MarketPlaceReview', title: 'MarketPlaceReview'), description: 'Reviews of this appliance, visible only when expanded'),
+        new OA\Property(property: 'capabilities', type: 'array', items: new OA\Items(type: 'OpenStackImplementationApiCoverage'), description: 'Capabilities of this appliance, visible only when requested as relation'),
+        new OA\Property(property: 'hypervisors', type: 'array', items: new OA\Items(type: 'HyperVisorType'), description: 'Hypervisors of this appliance, visible only when requested as relation'),
+        new OA\Property(property: 'guests', type: 'array', items: new OA\Items(type: 'GuestOSType'), description: 'GuestOSType of this appliance, visible only when requested as relation'),
+        new OA\Property(property: 'supported_regions', type: 'array', items: new OA\Items(type: 'RegionalSupport'), description: 'Regional support of this appliance, visible only when requested as relation'),
+    ],
+)]
+class MarketplaceAppliancesResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'PaginatedAppliancesResponse',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: 'data',
+                    type: 'array',
+                    items: new OA\Items(ref: '#/components/schemas/Appliance')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedAppliancesResponseSchema
+{
+}

app/Swagger/Models/ApplianceSchema.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'Appliance',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'created', type: 'integer', example: 1),
+        new OA\Property(property: 'last_edited', type: 'integer', example: 1),
+        new OA\Property(property: 'class_name', type: 'string', example: 'Appliance'),
+        new OA\Property(property: 'name', type: 'string', example: 'OpenStack Private Cloud Appliance'),
+        new OA\Property(property: 'overview', type: 'string', example: 'Complete OpenStack solution'),
+        new OA\Property(property: 'call_2_action_url', type: 'string', example: 'https://example.com/contact'),
+        new OA\Property(property: 'slug', type: 'string', example: 'openstack-appliance'),
+        new OA\Property(property: 'is_compatible_with_storage', type: 'boolean', example: true),
+        new OA\Property(property: 'is_compatible_with_compute', type: 'boolean', example: true),
+        new OA\Property(property: 'is_compatible_with_federated_identity', type: 'boolean', example: false),
+        new OA\Property(property: 'is_compatible_with_platform', type: 'boolean', example: true),
+        new OA\Property(property: 'is_openstack_powered', type: 'boolean', example: true),
+        new OA\Property(property: 'is_openstack_tested', type: 'boolean', example: true),
+        new OA\Property(property: 'openstack_tested_info', type: 'string', example: 'Tested with OpenStack Yoga'),
+        new OA\Property(property: 'company_id', type: 'integer', example: 41, description: 'ID of the company that provides this appliance, visible only when is not expanded'),
+        new OA\Property(property: 'company', ref: '#/components/schemas/Company', description: 'Company that provides this appliance, visible only when expanded'),
+        new OA\Property(property: 'type_id', type: 'integer', example: 13, description: 'ID of the MarketPlaceType of this appliance, visible only when not expanded'),
+        new OA\Property(property: 'reviews', type: 'array', items: new OA\Items(ref: '#/components/schemas/MarketPlaceReview', title: 'MarketPlaceReview'), description: 'Reviews of this appliance, visible only when expanded'),
+        new OA\Property(property: 'capabilities', type: 'array', items: new OA\Items(ref: '#/components/schemas/OpenStackImplementationApiCoverage'), description: 'Capabilities of this appliance, visible only when requested as relation'),
+        new OA\Property(property: 'hypervisors', type: 'array', items: new OA\Items(ref: '#/components/schemas/HyperVisorType'), description: 'Hypervisors of this appliance, visible only when requested as relation'),
+        new OA\Property(property: 'guests', type: 'array', items: new OA\Items(ref: '#/components/schemas/GuestOSType'), description: 'GuestOSType of this appliance, visible only when requested as relation'),
+        new OA\Property(property: 'supported_regions', type: 'array', items: new OA\Items(ref: '#/components/schemas/RegionalSupport'), description: 'Regional support of this appliance, visible only when requested as relation'),
+        // @TODO: Investigate how to reference properly, as it is present in ApplianceSerializer, but does not to have a serializer asociated
+        // new OA\Property(property: 'type', ref: '#/components/schemas/MarketPlaceType', description: 'MarketPlaceType of this appliance, visible only when expanded'),
+    ],
+)]
+class ApplianceSchema
+{
+}

app/Swagger/Models/MarketPlaceReviewSchema.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'MarketPlaceReview',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'created', type: 'integer', example: 1),
+        new OA\Property(property: 'last_edited', type: 'integer', example: 1),
+        new OA\Property(property: 'title', type: 'string'),
+        new OA\Property(property: 'comment', type: 'string'),
+        new OA\Property(property: 'rating', type: 'integer'),
+    ])
+]
+class MarketPlaceReviewSchema
+{
+}