Skip to content

Commit a360faa

Browse files
andrestejerina97andrestejerina97
committed
feat: Add openapi documentation for OAuth2SummitRegistrationCompaniesApiController
1 parent abbde7c commit a360faa

File tree

3 files changed

+222
-20
lines changed

3 files changed

+222
-20
lines changed

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

Lines changed: 127 additions & 20 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,35 @@ 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+
security: [["registration_companies_oauth2" => [
72+
SummitScopes::ReadAllSummitData,
73+
SummitScopes::ReadSummitData,
74+
]]],
75+
tags: ["RegistrationCompanies"],
76+
parameters: [
77+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
78+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
79+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
80+
new OA\Parameter(name: "filter", description: "Filter query (name==value, name=@value, name@@value)", in: "query", required: false, schema: new OA\Schema(type: "string")),
81+
new OA\Parameter(name: "order", description: "Order by (+name, -name)", in: "query", required: false, schema: new OA\Schema(type: "string")),
82+
],
83+
responses: [
84+
new OA\Response(
85+
response: Response::HTTP_OK,
86+
description: "OK",
87+
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedCompaniesResponse")
88+
),
89+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
90+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
91+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
92+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
93+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
94+
]
95+
)]
6796
public function getAllBySummit($summit_id)
6897
{
6998
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -106,25 +135,72 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use($summit) {
106135
);
107136
}
108137

109-
/**
110-
* @param $summit_id
111-
* @param $company_id
112-
* @return mixed
113-
*/
138+
#[OA\Put(
139+
path: "/api/v1/summits/{id}/registration-companies/{company_id}",
140+
summary: "Add a company to summit registration companies",
141+
description: "Associates a company with the summit for registration purposes (requires admin privileges)",
142+
x: [
143+
'required-groups' => [
144+
IGroup::SuperAdmins,
145+
IGroup::Administrators,
146+
IGroup::SummitAdministrators,
147+
IGroup::TrackChairsAdmins,
148+
]
149+
],
150+
security: [["registration_companies_oauth2" => [
151+
SummitScopes::WriteSummitData,
152+
]]],
153+
tags: ["RegistrationCompanies"],
154+
parameters: [
155+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
156+
new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
157+
],
158+
responses: [
159+
new OA\Response(response: Response::HTTP_CREATED, description: "Created"),
160+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
161+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
162+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
163+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
164+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
165+
]
166+
)]
114167
public function add($summit_id, $company_id)
115168
{
116-
117169
return $this->processRequest(function() use($summit_id, $company_id){
118170
$this->summit_service->addCompany(intval($summit_id), intval($company_id));
119171
return $this->created();
120172
});
121173
}
122174

123-
/**
124-
* @param $summit_id
125-
* @param $company_id
126-
* @return mixed
127-
*/
175+
#[OA\Delete(
176+
path: "/api/v1/summits/{id}/registration-companies/{company_id}",
177+
summary: "Remove a company from summit registration companies",
178+
description: "Disassociates a company from the summit registration (requires admin privileges)",
179+
x: [
180+
'required-groups' => [
181+
IGroup::SuperAdmins,
182+
IGroup::Administrators,
183+
IGroup::SummitAdministrators,
184+
IGroup::TrackChairsAdmins,
185+
]
186+
],
187+
security: [["registration_companies_oauth2" => [
188+
SummitScopes::WriteSummitData,
189+
]]],
190+
tags: ["RegistrationCompanies"],
191+
parameters: [
192+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
193+
new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
194+
],
195+
responses: [
196+
new OA\Response(response: Response::HTTP_NO_CONTENT, description: "No Content"),
197+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
198+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
199+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
200+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
201+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
202+
]
203+
)]
128204
public function delete($summit_id, $company_id)
129205
{
130206
return $this->processRequest(function() use($summit_id, $company_id){
@@ -133,11 +209,42 @@ public function delete($summit_id, $company_id)
133209
});
134210
}
135211

136-
/**
137-
* @param LaravelRequest $request
138-
* @param $summit_id
139-
* @return mixed
140-
*/
212+
#[OA\Post(
213+
path: "/api/v1/summits/{id}/registration-companies/csv",
214+
summary: "Import registration companies from CSV file",
215+
description: "Bulk import companies for summit registration from a CSV file (requires admin privileges)",
216+
x: [
217+
'required-groups' => [
218+
IGroup::SuperAdmins,
219+
IGroup::Administrators,
220+
IGroup::SummitAdministrators,
221+
IGroup::TrackChairsAdmins,
222+
]
223+
],
224+
security: [["registration_companies_oauth2" => [
225+
SummitScopes::WriteSummitData,
226+
]]],
227+
tags: ["RegistrationCompanies"],
228+
parameters: [
229+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
230+
],
231+
requestBody: new OA\RequestBody(
232+
required: true,
233+
content: new OA\MediaType(
234+
mediaType: "multipart/form-data",
235+
schema: new OA\Schema(ref: "#/components/schemas/ImportRegistrationCompaniesRequest")
236+
)
237+
),
238+
responses: [
239+
new OA\Response(response: Response::HTTP_OK, description: "OK - Companies imported successfully"),
240+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
241+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
242+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
243+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
244+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
245+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
246+
]
247+
)]
141248
public function import(LaravelRequest $request,$summit_id){
142249
return $this->processRequest(function() use($request, $summit_id){
143250
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);

‎app/Swagger/RegistrationCompaniesSchemas.php‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'Company',
9+
type: 'object',
10+
description: 'Base company information (public view)',
11+
properties: [
12+
new OA\Property(property: 'id', type: 'integer'),
13+
new OA\Property(property: 'created', type: 'integer'),
14+
new OA\Property(property: 'last_edited', type: 'integer'),
15+
new OA\Property(property: 'name', type: 'string'),
16+
new OA\Property(property: 'url', type: 'string', format: 'url', nullable: true),
17+
new OA\Property(property: 'url_segment', type: 'string', nullable: true),
18+
new OA\Property(property: 'city', type: 'string', nullable: true),
19+
new OA\Property(property: 'state', type: 'string', nullable: true),
20+
new OA\Property(property: 'country', type: 'string', nullable: true),
21+
new OA\Property(property: 'description', type: 'string', nullable: true),
22+
new OA\Property(property: 'industry', type: 'string', nullable: true),
23+
new OA\Property(property: 'contributions', type: 'string', nullable: true),
24+
new OA\Property(property: 'member_level', type: 'string', nullable: true),
25+
new OA\Property(property: 'overview', type: 'string', nullable: true),
26+
new OA\Property(property: 'products', type: 'string', nullable: true),
27+
new OA\Property(property: 'commitment', type: 'string', nullable: true),
28+
new OA\Property(property: 'commitment_author', type: 'string', nullable: true),
29+
new OA\Property(property: 'logo', type: 'string', format: 'url', nullable: true),
30+
new OA\Property(property: 'big_logo', type: 'string', format: 'url', nullable: true),
31+
new OA\Property(property: 'color', type: 'string', description: 'Hex color code', nullable: true),
32+
]
33+
)]
34+
class CompanySchema {}
35+
36+
#[OA\Schema(
37+
schema: 'PaginatedCompaniesResponse',
38+
type: 'object',
39+
description: 'Paginated response for registration companies',
40+
allOf: [
41+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
42+
new OA\Schema(
43+
type: 'object',
44+
properties: [
45+
new OA\Property(
46+
property: 'data',
47+
type: 'array',
48+
items: new OA\Items(ref: '#/components/schemas/Company')
49+
)
50+
]
51+
)
52+
]
53+
)]
54+
class PaginatedCompaniesResponseSchema {}
55+
56+
#[OA\Schema(
57+
schema: 'ImportRegistrationCompaniesRequest',
58+
type: 'object',
59+
description: 'Request to import registration companies from CSV file',
60+
required: ['file'],
61+
properties: [
62+
new OA\Property(
63+
property: 'file',
64+
type: 'string',
65+
format: 'binary',
66+
description: 'CSV file with company data'
67+
),
68+
]
69+
)]
70+
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)