Skip to content

Commit da8f95b

Browse files
matiasperrone-exosmarcetmatiasperrone
authored
Feature | Extend Swagger Coverage for controller OAuth2GroupsApiController (#365)
* fix: improve ticket csv serializer performance fix: improve ticket repository performance remove not needed extra joins fix: set fetchJoinCollection to false for ticket repo fix: get always owner to avoid N+1 on ticket repository fix: improve get tickets generic pagination * chore: refactor DoctrineSummitEventRepository to suppport 2 phase paging chore: fix .gitmessage.txt chore: increase header size to 150 * feat: Add OpenAPI documentation to "getAll" method - Add controller's response to OpenAPI schema * chore: Revert to main version due to conflicts with rebase * fix: comment * fix: Add security schema * fix: security schema class name * chore: ReadGroupsData was added to SummitScopes and the security schema was moved to its own file * chore: add requested changes in PR * chore: change namespace * chore: Add PR's requested changes Signed-off-by: Matias Perrone <github@matiasperrone.com> * chore: Use "Response" constansts for HTTP codes Signed-off-by: Matias Perrone <github@matiasperrone.com> --------- Signed-off-by: Matias Perrone <github@matiasperrone.com> Co-authored-by: smarcet <smarcet@gmail.com> Co-authored-by: Matias Perrone <github@matiasperrone.com>
1 parent 6c95448 commit da8f95b

File tree

5 files changed

+170
-8
lines changed

5 files changed

+170
-8
lines changed

‎app/Http/Controllers/Apis/Protected/Main/OAuth2GroupsApiController.php‎

Lines changed: 87 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
<?php namespace App\Http\Controllers;
1+
<?php
2+
namespace App\Http\Controllers;
23
/**
34
* Copyright 2017 OpenStack Foundation
45
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,9 +13,13 @@
1213
* limitations under the License.
1314
**/
1415

16+
use App\Security\GroupsScopes;
17+
use App\Security\SummitScopes;
18+
use Illuminate\Http\Response;
1519
use models\main\IGroupRepository;
1620
use models\oauth2\IResourceServerContext;
1721
use ModelSerializers\SerializerRegistry;
22+
use OpenApi\Attributes as OA;
1823

1924
/**
2025
* Class OAuth2GroupsApiController
@@ -26,20 +31,96 @@ final class OAuth2GroupsApiController extends OAuth2ProtectedController
2631
use ParametrizedGetAll;
2732

2833
/**
29-
* OAuth2MembersApiController constructor.
34+
* OAuth2GroupsApiController constructor.
3035
* @param IGroupRepository $group_repository
3136
* @param IResourceServerContext $resource_server_context
3237
*/
3338
public function __construct
3439
(
35-
IGroupRepository $group_repository,
40+
IGroupRepository $group_repository,
3641
IResourceServerContext $resource_server_context
37-
)
38-
{
42+
) {
3943
parent::__construct($resource_server_context);
4044
$this->repository = $group_repository;
4145
}
4246

47+
#[OA\Get(
48+
path: "/api/v1/groups",
49+
description: "Get all groups with filtering and pagination. Groups are used for access control and organization of members. Requires OAuth2 authentication with appropriate scope.",
50+
summary: 'Get all groups',
51+
operationId: 'getAllGroups',
52+
tags: ['Groups'],
53+
security: [
54+
[
55+
'groups_oauth2' => [
56+
SummitScopes::ReadAllSummitData,
57+
SummitScopes::ReadSummitData,
58+
GroupsScopes::ReadData,
59+
]
60+
]
61+
],
62+
parameters: [
63+
new OA\Parameter(
64+
name: 'access_token',
65+
in: 'query',
66+
required: false,
67+
description: 'OAuth2 access token (alternative to Authorization: Bearer)',
68+
schema: new OA\Schema(type: 'string', example: 'eyJhbGciOi...')
69+
),
70+
new OA\Parameter(
71+
name: 'page',
72+
in: 'query',
73+
required: false,
74+
description: 'Page number for pagination',
75+
schema: new OA\Schema(type: 'integer', example: 1)
76+
),
77+
new OA\Parameter(
78+
name: 'per_page',
79+
in: 'query',
80+
required: false,
81+
description: 'Items per page',
82+
schema: new OA\Schema(type: 'integer', example: 10, maximum: 100)
83+
),
84+
new OA\Parameter(
85+
name: 'filter[]',
86+
in: 'query',
87+
required: false,
88+
description: 'Filter expressions. Format: field<op>value. Available fields: code (=@, ==, @@), title (=@, ==, @@). Operators: == (equals), =@ (starts with), @@ (contains)',
89+
style: 'form',
90+
explode: true,
91+
schema: new OA\Schema(
92+
type: 'array',
93+
items: new OA\Items(type: 'string', example: 'code==administrators')
94+
)
95+
),
96+
new OA\Parameter(
97+
name: 'order',
98+
in: 'query',
99+
required: false,
100+
description: 'Order by field(s). Available fields: code, title, id. Use "-" prefix for descending order.',
101+
schema: new OA\Schema(type: 'string', example: 'title')
102+
),
103+
new OA\Parameter(
104+
name: 'expand',
105+
in: 'query',
106+
required: false,
107+
description: 'Comma-separated list of related resources to include. Available relations: members (expands member IDs to full member objects)',
108+
schema: new OA\Schema(type: 'string', example: 'members')
109+
),
110+
],
111+
responses: [
112+
new OA\Response(
113+
response: Response::HTTP_OK,
114+
description: 'Success - Returns paginated list of groups',
115+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedGroupsResponse')
116+
),
117+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request - Invalid parameters"),
118+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized - Invalid or missing access token"),
119+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - Insufficient permissions"),
120+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
121+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error")
122+
]
123+
)]
43124
public function getAll()
44125
{
45126
return $this->_getAll(
@@ -71,4 +152,4 @@ function () {
71152
);
72153
}
73154

74-
}
155+
}

‎app/Security/SummitScopes.php‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
<?php namespace App\Security;
1+
<?php
2+
namespace App\Security;
23
/**
34
* Copyright 2017 OpenStack Foundation
45
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -119,4 +120,5 @@ final class SummitScopes
119120

120121
const WriteAttendeeNotesData = '%s/attendee/notes/write';
121122
const ReadAttendeeNotesData = '%s/attendee/notes/read';
122-
}
123+
124+
}

‎app/Swagger/Models/GroupSchema.php‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
8+
#[OA\Schema(
9+
schema: 'Group',
10+
type: 'object',
11+
properties: [
12+
new OA\Property(property: 'id', type: 'integer', example: 1, description: 'Unique identifier'),
13+
new OA\Property(property: 'created', type: 'integer', example: 1630500518, description: 'Creation timestamp (Unix epoch)'),
14+
new OA\Property(property: 'last_edited', type: 'integer', example: 1630500518, description: 'Last modification timestamp (Unix epoch)'),
15+
new OA\Property(property: 'title', type: 'string', example: 'Administrators', description: 'Group title'),
16+
new OA\Property(property: 'description', type: 'string', example: 'System administrators group', description: 'Group description', nullable: true),
17+
new OA\Property(property: 'code', type: 'string', example: 'administrators', description: 'Unique group code'),
18+
new OA\Property(
19+
property: 'members',
20+
type: 'array',
21+
description: 'List of Member objects, only present when requested via ?expand=members',
22+
items: new OA\Items(
23+
ref: '#/components/schemas/Member'
24+
)
25+
),
26+
]
27+
)]
28+
class GroupSchema
29+
{
30+
}

‎app/Swagger/Security/GroupsOAuthSchema.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
namespace App\Swagger\schemas;
3+
4+
use OpenApi\Attributes as OA;
5+
use App\Security\GroupsScopes;
6+
use App\Security\SummitScopes;
7+
8+
#[OA\SecurityScheme(
9+
type: 'oauth2',
10+
securityScheme: 'groups_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+
GroupsScopes::ReadData => 'Read Groups Data',
20+
],
21+
),
22+
],
23+
)
24+
]
25+
class GroupsOAuthSchema
26+
{
27+
}

‎app/Swagger/schemas.php‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -736,6 +736,28 @@ class PaymentGatewayProfileCreateRequestSchema
736736
class PaymentGatewayProfileUpdateRequestSchema
737737
{
738738
}
739+
740+
741+
#[OA\Schema(
742+
schema: 'PaginatedGroupsResponse',
743+
allOf: [
744+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
745+
new OA\Schema(
746+
type: 'object',
747+
properties: [
748+
new OA\Property(
749+
property: 'data',
750+
type: 'array',
751+
items: new OA\Items(ref: '#/components/schemas/Group')
752+
)
753+
]
754+
)
755+
]
756+
)]
757+
class PaginatedGroupsResponseSchema
758+
{
759+
}
760+
739761
// User Stories
740762

741763

0 commit comments

Comments
 (0)