Skip to content

Commit a3eeb30

Browse files
matiasperrone-exomatiasperrone
matiasperrone-exo
and
matiasperrone
authored
Feature | Extend Swagger Coverage for controller OAuth2SummitMediaFileTypeApiController (#375)
* feat: Extend Swagger Coverage for controller Apis/Protected/Summit/OAuth2SummitMediaFileTypeApiController.php * fix: incorrect types and descriptions for errors * fix: incorrect types and descriptions for errors * fix: Move schema to the new file * fix: Change "namespace" word positioning * fix: add the right security schema * fix: security scopes * fix: security scopes array name * fix: Security schema * chore: Move the security schema for the controller to its own file * chore: change all tags to be **'Summit Media File Types'** * chore: add requested changes in PR --------- Co-authored-by: Matias Perrone <github@matiasperrone.com>
1 parent 90b84bc commit a3eeb30

File tree

3 files changed

+336
-2
lines changed

3 files changed

+336
-2
lines changed

‎app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitMediaFileTypeApiController.php‎

Lines changed: 236 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 2020 OpenStack Foundation
47
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -11,11 +14,16 @@
1114
* See the License for the specific language governing permissions and
1215
* limitations under the License.
1316
**/
17+
use App\Models\Foundation\Main\IGroup;
1418
use App\Models\Foundation\Summit\Repositories\ISummitMediaFileTypeRepository;
19+
use App\Security\SummitScopes;
1520
use App\Services\Model\ISummitMediaFileTypeService;
1621
use models\oauth2\IResourceServerContext;
1722
use models\utils\IEntity;
1823
use ModelSerializers\SerializerRegistry;
24+
use OpenApi\Attributes as OA;
25+
use Symfony\Component\HttpFoundation\Response;
26+
1927
/**
2028
* Class OAuth2SummitMediaFileTypeApiController
2129
* @package App\Http\Controllers
@@ -55,6 +63,232 @@ public function __construct
5563
$this->repository = $repository;
5664
}
5765

66+
// OpenAPI Documentation
67+
68+
#[OA\Get(
69+
path: '/api/v1/summit-media-file-types',
70+
operationId: 'getAllSummitMediaFileTypes',
71+
summary: 'Get all summit media file types',
72+
description: 'Retrieves a paginated list of summit media file types. Media file types define categories of files that can be uploaded to summits (e.g., presentations, videos, documents) along with their allowed file extensions.',
73+
x: [
74+
'required-groups' => [
75+
IGroup::SuperAdmins,
76+
IGroup::Administrators,
77+
IGroup::SummitAdministrators,
78+
]
79+
],
80+
security: [['summit_media_file_type_oauth2' => [
81+
SummitScopes::ReadSummitMediaFileTypes
82+
]]],
83+
tags: ['Summit Media File Types'],
84+
parameters: [
85+
new OA\Parameter(
86+
name: 'page',
87+
in: 'query',
88+
required: false,
89+
description: 'Page number for pagination',
90+
schema: new OA\Schema(type: 'integer', example: 1)
91+
),
92+
new OA\Parameter(
93+
name: 'per_page',
94+
in: 'query',
95+
required: false,
96+
description: 'Items per page',
97+
schema: new OA\Schema(type: 'integer', example: 10, maximum: 100)
98+
),
99+
new OA\Parameter(
100+
name: 'filter[]',
101+
in: 'query',
102+
required: false,
103+
description: 'Filter expressions. Format: field<op>value. Available field: name (=@, ==). Operators: == (equals), =@ (starts with)',
104+
style: 'form',
105+
explode: true,
106+
schema: new OA\Schema(
107+
type: 'array',
108+
items: new OA\Items(type: 'string', example: 'name@@presentation')
109+
)
110+
),
111+
new OA\Parameter(
112+
name: 'order',
113+
in: 'query',
114+
required: false,
115+
description: 'Order by field(s). Available fields: name, id. Use "-" prefix for descending order.',
116+
schema: new OA\Schema(type: 'string', example: 'name')
117+
),
118+
],
119+
responses: [
120+
new OA\Response(
121+
response: 200,
122+
description: 'Media file types retrieved successfully',
123+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedSummitMediaFileTypesResponse')
124+
),
125+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
126+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
127+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
128+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
129+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
130+
]
131+
)]
132+
133+
#[OA\Get(
134+
path: '/api/v1/summit-media-file-types/{id}',
135+
operationId: 'getSummitMediaFileType',
136+
summary: 'Get a summit media file type by ID',
137+
description: 'Retrieves detailed information about a specific summit media file type.',
138+
x: [
139+
'required-groups' => [
140+
IGroup::SuperAdmins,
141+
IGroup::Administrators,
142+
IGroup::SummitAdministrators,
143+
]
144+
],
145+
security: [['summit_media_file_type_oauth2' => [
146+
SummitScopes::ReadSummitMediaFileTypes
147+
]]],
148+
tags: ['Summit Media File Types'],
149+
parameters: [
150+
new OA\Parameter(
151+
name: 'id',
152+
in: 'path',
153+
required: true,
154+
description: 'Summit Media File Type ID',
155+
schema: new OA\Schema(type: 'integer')
156+
),
157+
],
158+
responses: [
159+
new OA\Response(
160+
response: 200,
161+
description: 'Media file type retrieved successfully',
162+
content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileType')
163+
),
164+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
165+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
166+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
167+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
168+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
169+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
170+
]
171+
)]
172+
173+
#[OA\Post(
174+
path: '/api/v1/summit-media-file-types',
175+
operationId: 'createSummitMediaFileType',
176+
summary: 'Create a new summit media file type',
177+
description: 'Creates a new summit media file type with specified name, description, and allowed file extensions.',
178+
x: [
179+
'required-groups' => [
180+
IGroup::SuperAdmins,
181+
IGroup::Administrators,
182+
IGroup::SummitAdministrators,
183+
]
184+
],
185+
security: [['summit_media_file_type_oauth2' => [
186+
SummitScopes::WriteSummitMediaFileTypes
187+
]]],
188+
tags: ['Summit Media File Types'],
189+
requestBody: new OA\RequestBody(
190+
required: true,
191+
content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileTypeCreateRequest')
192+
),
193+
responses: [
194+
new OA\Response(
195+
response: 201,
196+
description: 'Media file type created successfully',
197+
content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileType')
198+
),
199+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
200+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
201+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
202+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
203+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
204+
new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: "Validation Error"),
205+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
206+
]
207+
)]
208+
209+
#[OA\Put(
210+
path: '/api/v1/summit-media-file-types/{id}',
211+
operationId: 'updateSummitMediaFileType',
212+
summary: 'Update a summit media file type',
213+
description: 'Updates an existing summit media file type.',
214+
x: [
215+
'required-groups' => [
216+
IGroup::SuperAdmins,
217+
IGroup::Administrators,
218+
IGroup::SummitAdministrators,
219+
]
220+
],
221+
security: [['summit_media_file_type_oauth2' => [
222+
SummitScopes::WriteSummitMediaFileTypes
223+
]]],
224+
tags: ['Summit Media File Types'],
225+
parameters: [
226+
new OA\Parameter(
227+
name: 'id',
228+
in: 'path',
229+
required: true,
230+
description: 'Summit Media File Type ID',
231+
schema: new OA\Schema(type: 'integer')
232+
),
233+
],
234+
requestBody: new OA\RequestBody(
235+
required: true,
236+
content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileTypeUpdateRequest')
237+
),
238+
responses: [
239+
new OA\Response(
240+
response: 200,
241+
description: 'Media file type updated successfully',
242+
content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileType')
243+
),
244+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
245+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
246+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
247+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
248+
new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: "Validation Error"),
249+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
250+
]
251+
)]
252+
253+
#[OA\Delete(
254+
path: '/api/v1/summit-media-file-types/{id}',
255+
operationId: 'deleteSummitMediaFileType',
256+
summary: 'Delete a summit media file type',
257+
description: 'Deletes an existing summit media file type. System-defined types cannot be deleted.',
258+
x: [
259+
'required-groups' => [
260+
IGroup::SuperAdmins,
261+
IGroup::Administrators,
262+
IGroup::SummitAdministrators,
263+
]
264+
],
265+
security: [['summit_media_file_type_oauth2' => [
266+
SummitScopes::WriteSummitMediaFileTypes
267+
]]],
268+
tags: ['Summit Media File Types'],
269+
parameters: [
270+
new OA\Parameter(
271+
name: 'id',
272+
in: 'path',
273+
required: true,
274+
description: 'Summit Media File Type ID',
275+
schema: new OA\Schema(type: 'integer')
276+
),
277+
],
278+
responses: [
279+
new OA\Response(
280+
response: 204,
281+
description: 'Media file type deleted successfully'
282+
),
283+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
284+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
285+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
286+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
287+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
288+
new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: "Validation Error"),
289+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
290+
]
291+
)]
58292

59293
/**
60294
* @inheritDoc
@@ -139,4 +373,4 @@ function(){
139373
}
140374
);
141375
}
142-
}
376+
}

‎app/Swagger/Security/SummitMediaFileTypeAuthSchema.php‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use App\Security\SummitScopes;
6+
use OpenApi\Attributes as OA;
7+
8+
9+
10+
#[OA\SecurityScheme(
11+
type: 'oauth2',
12+
securityScheme: 'summit_media_file_type_oauth2',
13+
flows: [
14+
new OA\Flow(
15+
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
16+
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
17+
flow: 'authorizationCode',
18+
scopes: [
19+
SummitScopes::ReadSummitMediaFileTypes => 'Read Summit Media File Types',
20+
SummitScopes::WriteSummitMediaFileTypes => 'Write Summit Media File Types',
21+
],
22+
),
23+
],
24+
)
25+
]
26+
class SummitMediaFileTypeAuthSchema{}

‎app/Swagger/SummitSchemas.php‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,77 @@
55
use OpenApi\Attributes as OA;
66

77
//
8+
9+
#[OA\Schema(
10+
schema: 'SummitMediaFileType',
11+
type: 'object',
12+
properties: [
13+
new OA\Property(property: 'id', type: 'integer', example: 1),
14+
new OA\Property(property: 'created', type: 'integer', format: 'int64', example: 1633024800),
15+
new OA\Property(property: 'last_edited', type: 'integer', format: 'int64', example: 1633024800),
16+
new OA\Property(property: 'name', type: 'string', example: 'Presentation'),
17+
new OA\Property(property: 'description', type: 'string', example: 'Presentation files for events'),
18+
new OA\Property(property: 'is_system_defined', type: 'boolean', example: false),
19+
new OA\Property(
20+
property: 'allowed_extensions',
21+
type: 'array',
22+
items: new OA\Items(type: 'string'),
23+
example: ['pdf', 'ppt', 'pptx']
24+
),
25+
]
26+
)]
27+
class SummitMediaFileTypeSchema {}
28+
29+
#[OA\Schema(
30+
schema: 'PaginatedSummitMediaFileTypesResponse',
31+
type: 'object',
32+
allOf: [
33+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
34+
new OA\Schema(
35+
properties: [
36+
new OA\Property(
37+
property: 'data',
38+
type: 'array',
39+
items: new OA\Items(ref: '#/components/schemas/SummitMediaFileType')
40+
)
41+
]
42+
)
43+
]
44+
)]
45+
class PaginatedSummitMediaFileTypesResponseSchema {}
46+
47+
#[OA\Schema(
48+
schema: 'SummitMediaFileTypeCreateRequest',
49+
required: ['name', 'allowed_extensions'],
50+
type: 'object',
51+
properties: [
52+
new OA\Property(property: 'name', type: 'string', maxLength: 255, example: 'Presentation'),
53+
new OA\Property(property: 'description', type: 'string', maxLength: 255, example: 'Presentation files for events'),
54+
new OA\Property(
55+
property: 'allowed_extensions',
56+
type: 'array',
57+
items: new OA\Items(type: 'string'),
58+
example: ['pdf', 'ppt', 'pptx'],
59+
description: 'Array of allowed file extensions'
60+
),
61+
]
62+
)]
63+
class SummitMediaFileTypeCreateRequestSchema {}
64+
65+
#[OA\Schema(
66+
schema: 'SummitMediaFileTypeUpdateRequest',
67+
required: ['allowed_extensions'],
68+
type: 'object',
69+
properties: [
70+
new OA\Property(property: 'name', type: 'string', maxLength: 255, example: 'Presentation'),
71+
new OA\Property(property: 'description', type: 'string', maxLength: 255, example: 'Presentation files for events'),
72+
new OA\Property(
73+
property: 'allowed_extensions',
74+
type: 'array',
75+
items: new OA\Items(type: 'string'),
76+
example: ['pdf', 'ppt', 'pptx'],
77+
description: 'Array of allowed file extensions'
78+
),
79+
]
80+
)]
81+
class SummitMediaFileTypeUpdateRequestSchema {}

0 commit comments

Comments
 (0)