Skip to content

Commit 60d5b97

Browse files
matiasperrone-exomatiasperrone
matiasperrone-exo
and
matiasperrone
authored
Feature | Extend Swagger Coverage for controller PublicCloudsApiController (#362)
* feat: Add OpenAPI documentation to "getAll" method * chore: Add controller's response OpenAPI schema * chore: change schema name to be reused by private cloud controller too * chore: remove unnecessary and conflicting require and move schema to Marketplace Schemas file * fix: fix typo * fix: Change "namespace" word positioning * fix: remove "Schema" string from schema name * fix: comment * chore: Move to Marketplace single tag * chore: update with refs * feat: add OpenAPI documentation for CloudService, DataCenterLocation, and DataCenterRegion schemas * chore: add requested changes --------- Co-authored-by: Matias Perrone <github@matiasperrone.com>
1 parent 55c999b commit 60d5b97

6 files changed

Lines changed: 171 additions & 2 deletions

File tree

‎app/Http/Controllers/Apis/Marketplace/PublicCloudsApiController.php‎

Lines changed: 79 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
<?php namespace App\Http\Controllers;
1+
<?php
2+
3+
namespace App\Http\Controllers;
4+
25
/**
36
* Copyright 2017 OpenStack Foundation
47
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,7 +15,9 @@
1215
* limitations under the License.
1316
**/
1417
use App\Models\Foundation\Marketplace\IPublicCloudServiceRepository;
18+
use Illuminate\Http\Response;
1519
use models\oauth2\IResourceServerContext;
20+
use OpenApi\Attributes as OA;
1621

1722
/**
1823
* Class PublicCloudsApiController
@@ -21,14 +26,86 @@
2126
final class PublicCloudsApiController extends AbstractCompanyServiceApiController
2227
{
2328
/**
24-
* PrivateCloudsApiController constructor.
29+
* PublicCloudsApiController constructor.
2530
* @param IPublicCloudServiceRepository $repository
2631
*/
2732
public function __construct(IPublicCloudServiceRepository $repository, IResourceServerContext $resource_server_context)
2833
{
2934
parent::__construct($repository, $resource_server_context);
3035
}
3136

37+
#[OA\Get(
38+
path: "/api/public/v1/marketplace/public-clouds",
39+
description: "Get all marketplace public cloud services (OpenStack implementations)",
40+
summary: 'Get all public clouds',
41+
operationId: 'getAllPublicClouds',
42+
tags: ['Marketplace', 'Clouds'],
43+
parameters: [
44+
new OA\Parameter(
45+
name: 'page',
46+
in: 'query',
47+
required: false,
48+
description: 'Page number for pagination',
49+
schema: new OA\Schema(type: 'integer', example: 1)
50+
),
51+
new OA\Parameter(
52+
name: 'per_page',
53+
in: 'query',
54+
required: false,
55+
description: 'Items per page',
56+
schema: new OA\Schema(type: 'integer', example: 10, maximum: 100)
57+
),
58+
new OA\Parameter(
59+
name: 'filter[]',
60+
in: 'query',
61+
required: false,
62+
description: 'Filter expressions in the format field<op>value. Available fields: name, company. Operators: =@, ==, @@.',
63+
style: 'form',
64+
explode: true,
65+
schema: new OA\Schema(
66+
type: 'array',
67+
items: new OA\Items(type: 'string', example: 'name@@aws')
68+
)
69+
),
70+
new OA\Parameter(
71+
name: 'order',
72+
in: 'query',
73+
required: false,
74+
description: 'Order by field(s)',
75+
schema: new OA\Schema(type: 'string', example: 'name,-id')
76+
),
77+
new OA\Parameter(
78+
name: 'expand',
79+
in: 'query',
80+
required: false,
81+
description: 'Comma-separated list of related resources to include. Available relations: company, type, capabilities, guests, hypervisors, supported_regions, data_centers, data_center_regions',
82+
schema: new OA\Schema(type: 'string', example: 'company,data_centers')
83+
),
84+
new OA\Parameter(
85+
name: 'relations',
86+
in: 'query',
87+
required: false,
88+
description: 'Relations to load eagerly',
89+
schema: new OA\Schema(type: 'string', example: 'company,data_centers')
90+
),
91+
new OA\Parameter(
92+
name: 'fields',
93+
in: 'query',
94+
required: false,
95+
description: 'Comma-separated list of fields to return',
96+
schema: new OA\Schema(type: 'string', example: 'id,name,company.name')
97+
),
98+
],
99+
responses: [
100+
new OA\Response(
101+
response: 200,
102+
description: 'Success - Returns paginated list of public clouds',
103+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedPublicOrPrivateCloudsResponse')
104+
),
105+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
106+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error")
107+
]
108+
)]
32109
public function getAll()
33110
{
34111
return parent::getAll();

‎app/Swagger/MarketplaceSchemas.php‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,3 +65,23 @@ class PaginatedConsultantsResponseSchema
6565
class PaginatedMarketplaceDistributionResponseSchema
6666
{
6767
}
68+
69+
#[OA\Schema(
70+
schema: 'PaginatedPublicOrPrivateCloudsResponse',
71+
allOf: [
72+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
73+
new OA\Schema(
74+
type: 'object',
75+
properties: [
76+
new OA\Property(
77+
property: 'data',
78+
type: 'array',
79+
items: new OA\Items(ref: '#/components/schemas/CloudService')
80+
)
81+
]
82+
)
83+
]
84+
)]
85+
class PaginatedPublicOrPrivateCloudsResponseSchema
86+
{
87+
}

‎app/Swagger/Models/CloudServiceSchema.php‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
8+
#[OA\Schema(
9+
schema: 'CloudService',
10+
allOf: [
11+
new OA\Schema(ref: '#/components/schemas/OpenStackImplementation'),
12+
new OA\Schema(
13+
type: 'object',
14+
properties: [
15+
new OA\Property(property: 'data_centers', type: 'array', items: new OA\Items(ref: '#/components/schemas/DataCenterLocation'), description: 'List of DataCenterLocation objects associated with this CloudService, only if ?relations=data_centers is used in the query string'),
16+
new OA\Property(property: 'data_center_regions', type: 'array', items: new OA\Items(ref: '#/components/schemas/DataCenterRegion'), description: 'List of DataCenterRegion objects associated with this CloudService, only if ?relations=data_center_regions is used in the query string'),
17+
]
18+
),
19+
],
20+
)]
21+
class CloudServiceSchema
22+
{
23+
}

‎app/Swagger/Models/DataCenterLocationSchema.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
8+
#[OA\Schema(
9+
schema: 'DataCenterLocation',
10+
type: 'object',
11+
properties: [
12+
new OA\Property(property: 'id', type: 'integer', example: 1),
13+
new OA\Property(property: 'created', type: 'integer', example: 1),
14+
new OA\Property(property: 'last_edited', type: 'integer', example: 1),
15+
new OA\Property(property: 'city', type: 'string', example: 'New York'),
16+
new OA\Property(property: 'state', type: 'string', example: 'NY'),
17+
new OA\Property(property: 'country', type: 'string', example: 'USA'),
18+
new OA\Property(property: 'lat', type: 'number', example: 40.7128),
19+
new OA\Property(property: 'lng', type: 'number', example: -74.0060),
20+
new OA\Property(property: 'region_id', type: 'integer', example: 1, description: 'DataCenterRegion ID'),
21+
new OA\Property(property: 'region', ref: '#/components/schemas/DataCenterRegion', description: 'DataCenterRegion object, only present if ?expand=region is used in the query string'),
22+
23+
])
24+
]
25+
class DataCenterLocationSchema
26+
{
27+
}

‎app/Swagger/Models/DataCenterRegionSchema.php‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
8+
#[OA\Schema(
9+
schema: 'DataCenterRegion',
10+
type: 'object',
11+
properties: [
12+
new OA\Property(property: 'id', type: 'integer', example: 1),
13+
new OA\Property(property: 'created', type: 'integer', example: 1),
14+
new OA\Property(property: 'last_edited', type: 'integer', example: 1),
15+
new OA\Property(property: 'name', type: 'string', example: 'Data Center 1'),
16+
new OA\Property(property: 'endpoint', type: 'string', example: 'https://endpoint.example.com'),
17+
])
18+
]
19+
class DataCenterRegionSchema
20+
{
21+
}

‎app/Swagger/schemas.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -416,3 +416,4 @@ class ChunkedFileUploadCompleteResponseSchema {}
416416
]
417417
)]
418418
class ChunkedFileUploadRequestSchema {}
419+

0 commit comments

Comments
 (0)