Skip to content

Commit 5fed732

Browse files
andrestejerina97matiasperrone
andrestejerina97
and
matiasperrone
authored
Feature | Extend Swagger Coverage for controller OAuth2SummitRegistrationCompaniesApiController (#459)
* feat: Add openapi documentation for OAuth2SummitRegistrationCompaniesApiController * chore: Add PR's requested changes * chore: Add PR's requested changes * fix: merge conflict Signed-off-by: Matias Perrone <github@matiasperrone.com> * chore: Add operationId Signed-off-by: Matias Perrone <github@matiasperrone.com> * fix: merge conflict Signed-off-by: Matias Perrone <github@matiasperrone.com> --------- Signed-off-by: Matias Perrone <github@matiasperrone.com> Co-authored-by: Matias Perrone <github@matiasperrone.com>
1 parent 9907ae7 commit 5fed732

3 files changed

Lines changed: 194 additions & 21 deletions

File tree

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

Lines changed: 148 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,17 @@
1212
* limitations under the License.
1313
**/
1414

15+
use App\Models\Foundation\Main\IGroup;
16+
use App\Security\SummitScopes;
1517
use Illuminate\Http\Request as LaravelRequest;
1618
use Illuminate\Support\Facades\Validator;
1719
use models\exceptions\ValidationException;
1820
use models\oauth2\IResourceServerContext;
1921
use models\summit\ISummitRepository;
2022
use ModelSerializers\SerializerRegistry;
23+
use OpenApi\Attributes as OA;
2124
use services\model\ISummitService;
25+
use Symfony\Component\HttpFoundation\Response;
2226
use utils\PagingInfo;
2327

2428
/**
@@ -60,10 +64,40 @@ public function __construct
6064
$this->summit_service = $summit_service;
6165
}
6266

63-
/**
64-
* @param $summit_id
65-
* @return mixed
66-
*/
67+
#[OA\Get(
68+
path: "/api/v1/summits/{id}/registration-companies",
69+
summary: "Get all registration companies for a summit",
70+
description: "Returns list of companies that have registered attendees for this summit",
71+
operationId: "getAllRegistrationCompaniesBySummit",
72+
security: [
73+
[
74+
"registration_companies_oauth2" => [
75+
SummitScopes::ReadAllSummitData,
76+
SummitScopes::ReadSummitData,
77+
]
78+
]
79+
],
80+
tags: ["Registration Companies"],
81+
parameters: [
82+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
83+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
84+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
85+
new OA\Parameter(name: "filter", description: "Filter query (name==value, name=@value, name@@value)", in: "query", required: false, schema: new OA\Schema(type: "string")),
86+
new OA\Parameter(name: "order", description: "Order by (+name, -name)", in: "query", required: false, schema: new OA\Schema(type: "string")),
87+
],
88+
responses: [
89+
new OA\Response(
90+
response: Response::HTTP_OK,
91+
description: "OK",
92+
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedCompaniesResponse")
93+
),
94+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
95+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
96+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
97+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
98+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
99+
]
100+
)]
67101
public function getAllBySummit($summit_id)
68102
{
69103
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -106,25 +140,82 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use($summit) {
106140
);
107141
}
108142

109-
/**
110-
* @param $summit_id
111-
* @param $company_id
112-
* @return mixed
113-
*/
143+
#[OA\Put(
144+
path: "/api/v1/summits/{id}/registration-companies/{company_id}",
145+
summary: "Add a company to summit registration companies",
146+
description: "Associates a company with the summit for registration purposes (requires admin privileges)",
147+
operationId: "addRegistrationCompany",
148+
x: [
149+
'required-groups' => [
150+
IGroup::SuperAdmins,
151+
IGroup::Administrators,
152+
IGroup::SummitAdministrators,
153+
IGroup::TrackChairsAdmins,
154+
]
155+
],
156+
security: [
157+
[
158+
"registration_companies_oauth2" => [
159+
SummitScopes::WriteSummitData,
160+
]
161+
]
162+
],
163+
tags: ["Registration Companies"],
164+
parameters: [
165+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
166+
new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
167+
],
168+
responses: [
169+
new OA\Response(response: Response::HTTP_CREATED, description: "Created"),
170+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
171+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
172+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
173+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
174+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
175+
]
176+
)]
114177
public function add($summit_id, $company_id)
115178
{
116-
117179
return $this->processRequest(function() use($summit_id, $company_id){
118180
$this->summit_service->addCompany(intval($summit_id), intval($company_id));
119181
return $this->created();
120182
});
121183
}
122184

123-
/**
124-
* @param $summit_id
125-
* @param $company_id
126-
* @return mixed
127-
*/
185+
#[OA\Delete(
186+
path: "/api/v1/summits/{id}/registration-companies/{company_id}",
187+
summary: "Remove a company from summit registration companies",
188+
description: "Disassociates a company from the summit registration (requires admin privileges)",
189+
operationId: "deleteRegistrationCompany",
190+
x: [
191+
'required-groups' => [
192+
IGroup::SuperAdmins,
193+
IGroup::Administrators,
194+
IGroup::SummitAdministrators,
195+
IGroup::TrackChairsAdmins,
196+
]
197+
],
198+
security: [
199+
[
200+
"registration_companies_oauth2" => [
201+
SummitScopes::WriteSummitData,
202+
]
203+
]
204+
],
205+
tags: ["Registration Companies"],
206+
parameters: [
207+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
208+
new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
209+
],
210+
responses: [
211+
new OA\Response(response: Response::HTTP_NO_CONTENT, description: "No Content"),
212+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
213+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
214+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
215+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
216+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
217+
]
218+
)]
128219
public function delete($summit_id, $company_id)
129220
{
130221
return $this->processRequest(function() use($summit_id, $company_id){
@@ -133,11 +224,47 @@ public function delete($summit_id, $company_id)
133224
});
134225
}
135226

136-
/**
137-
* @param LaravelRequest $request
138-
* @param $summit_id
139-
* @return mixed
140-
*/
227+
#[OA\Post(
228+
path: "/api/v1/summits/{id}/registration-companies/csv",
229+
summary: "Import registration companies from CSV file",
230+
description: "Bulk import companies for summit registration from a CSV file (requires admin privileges)",
231+
operationId: "importRegistrationCompanies",
232+
x: [
233+
'required-groups' => [
234+
IGroup::SuperAdmins,
235+
IGroup::Administrators,
236+
IGroup::SummitAdministrators,
237+
IGroup::TrackChairsAdmins,
238+
]
239+
],
240+
security: [
241+
[
242+
"registration_companies_oauth2" => [
243+
SummitScopes::WriteSummitData,
244+
]
245+
]
246+
],
247+
tags: ["Registration Companies"],
248+
parameters: [
249+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
250+
],
251+
requestBody: new OA\RequestBody(
252+
required: true,
253+
content: new OA\MediaType(
254+
mediaType: "multipart/form-data",
255+
schema: new OA\Schema(ref: "#/components/schemas/ImportRegistrationCompaniesRequest")
256+
)
257+
),
258+
responses: [
259+
new OA\Response(response: Response::HTTP_OK, description: "OK - Companies imported successfully"),
260+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
261+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
262+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
263+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
264+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
265+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
266+
]
267+
)]
141268
public function import(LaravelRequest $request,$summit_id){
142269
return $this->processRequest(function() use($request, $summit_id){
143270
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -166,4 +293,4 @@ public function import(LaravelRequest $request,$summit_id){
166293

167294
});
168295
}
169-
}
296+
}

‎app/Swagger/RegistrationCompaniesSchemas.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+
#[OA\Schema(
8+
schema: 'ImportRegistrationCompaniesRequest',
9+
type: 'object',
10+
description: 'Request to import registration companies from CSV file',
11+
required: ['file'],
12+
properties: [
13+
new OA\Property(
14+
property: 'file',
15+
type: 'string',
16+
format: 'binary',
17+
description: 'CSV file with company data'
18+
),
19+
]
20+
)]
21+
class ImportRegistrationCompaniesRequestSchema {}

‎app/Swagger/Security/RegistrationCompaniesOauth2.php‎

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

0 commit comments

Comments
 (0)