Skip to content

Commit f8411d1

Browse files
alexmerlinalexmerlin
committed
Issue #168: OpenAPI documentation
Signed-off-by: alexmerlin <alex.merlin.1985@gmail.com>
1 parent 80ddda3 commit f8411d1

15 files changed

Lines changed: 413 additions & 46 deletions

‎composer.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,6 @@
7979
"mezzio/mezzio-twigrenderer": "^2.15.0",
8080
"ramsey/uuid-doctrine": "^2.1.0",
8181
"roave/psr-container-doctrine": "^5.1.0",
82-
"swagger-api/swagger-ui": "^5.17",
8382
"symfony/filesystem": "^7.0.3",
8483
"zircote/swagger-php": "^4.10"
8584
},

‎src/Admin/src/Handler/AdminHandler.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,9 @@ public function get(ServerRequestInterface $request): ResponseInterface
5858
return $this->createResponse($request, $admin);
5959
}
6060

61+
/**
62+
* @throws BadRequestException
63+
*/
6164
public function getCollection(ServerRequestInterface $request): ResponseInterface
6265
{
6366
return $this->createResponse($request, $this->adminService->getAdmins($request->getQueryParams()));

‎src/Admin/src/Handler/AdminRoleHandler.php‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
namespace Api\Admin\Handler;
66

77
use Api\Admin\Service\AdminRoleServiceInterface;
8+
use Api\App\Exception\BadRequestException;
89
use Api\App\Exception\NotFoundException;
910
use Api\App\Handler\HandlerTrait;
1011
use Dot\DependencyInjection\Attribute\Inject;
@@ -42,11 +43,11 @@ public function get(ServerRequestInterface $request): ResponseInterface
4243
return $this->createResponse($request, $role);
4344
}
4445

46+
/**
47+
* @throws BadRequestException
48+
*/
4549
public function getCollection(ServerRequestInterface $request): ResponseInterface
4650
{
47-
return $this->createResponse(
48-
$request,
49-
$this->roleService->getAdminRoles($request->getQueryParams())
50-
);
51+
return $this->createResponse($request, $this->roleService->getAdminRoles($request->getQueryParams()));
5152
}
5253
}

‎src/Admin/src/OpenAPI.php‎

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
namespace Api\Admin;
66

7+
use Api\Admin\Collection\AdminCollection;
8+
use Api\Admin\Collection\AdminRoleCollection;
79
use Api\Admin\Entity\Admin;
810
use Api\Admin\Entity\AdminRole;
911
use Api\Admin\Handler\AdminAccountHandler;
@@ -192,6 +194,11 @@
192194
description: 'List of admin accounts',
193195
content: new OA\JsonContent(ref: '#/components/schemas/AdminCollection'),
194196
),
197+
new OA\Response(
198+
response: StatusCodeInterface::STATUS_BAD_REQUEST,
199+
description: 'Bad Request',
200+
content: new OA\JsonContent(ref: '#/components/schemas/ErrorMessage'),
201+
),
195202
new OA\Response(
196203
response: StatusCodeInterface::STATUS_NOT_FOUND,
197204
description: 'Not Found',
@@ -279,7 +286,7 @@
279286
content: new OA\JsonContent(
280287
required: ['identity', 'password', 'passwordConfirm', 'firstName', 'lastName', 'roles'],
281288
properties: [
282-
new OA\Property(property: 'identity', type: 'string', default: 'password'),
289+
new OA\Property(property: 'identity', type: 'string'),
283290
new OA\Property(property: 'password', type: 'string'),
284291
new OA\Property(property: 'passwordConfirm', type: 'string'),
285292
new OA\Property(property: 'firstName', type: 'string'),
@@ -332,7 +339,7 @@
332339
description: 'Authenticated (super)admin fetches an admin role identified by its UUID',
333340
summary: 'Admin fetches an admin role',
334341
security: [['AuthToken' => []]],
335-
tags: ['Admin Role'],
342+
tags: ['AdminRole'],
336343
parameters: [
337344
new OA\Parameter(
338345
name: 'uuid',
@@ -363,7 +370,7 @@
363370
description: 'Authenticated (super)admin fetches a list of admin roles',
364371
summary: 'Admin lists admin roles',
365372
security: [['AuthToken' => []]],
366-
tags: ['Admin Role'],
373+
tags: ['AdminRole'],
367374
parameters: [
368375
new OA\Parameter(
369376
name: 'page',
@@ -409,7 +416,12 @@
409416
new OA\Response(
410417
response: StatusCodeInterface::STATUS_OK,
411418
description: 'List of admin accounts',
412-
content: new OA\JsonContent(ref: '#/components/schemas/AdminCollection'),
419+
content: new OA\JsonContent(ref: '#/components/schemas/AdminRoleCollection'),
420+
),
421+
new OA\Response(
422+
response: StatusCodeInterface::STATUS_BAD_REQUEST,
423+
description: 'Bad Request',
424+
content: new OA\JsonContent(ref: '#/components/schemas/ErrorMessage'),
413425
),
414426
new OA\Response(
415427
response: StatusCodeInterface::STATUS_NOT_FOUND,
@@ -492,6 +504,9 @@
492504
type: 'object',
493505
)]
494506

507+
/**
508+
* @see AdminCollection
509+
*/
495510
#[OA\Schema(
496511
schema: 'AdminCollection',
497512
properties: [
@@ -514,6 +529,31 @@
514529
new OA\Schema(ref: '#/components/schemas/Collection'),
515530
],
516531
)]
532+
/**
533+
* @see AdminRoleCollection
534+
*/
535+
#[OA\Schema(
536+
schema: 'AdminRoleCollection',
537+
properties: [
538+
new OA\Property(
539+
property: '_embedded',
540+
properties: [
541+
new OA\Property(
542+
property: 'roles',
543+
type: 'array',
544+
items: new OA\Items(
545+
ref: '#/components/schemas/AdminRole',
546+
),
547+
),
548+
],
549+
type: 'object',
550+
),
551+
],
552+
type: 'object',
553+
allOf: [
554+
new OA\Schema(ref: '#/components/schemas/Collection'),
555+
],
556+
)]
517557

518558
class OpenAPI
519559
{

‎src/Admin/src/Service/AdminRoleService.php‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
use Api\Admin\Collection\AdminRoleCollection;
88
use Api\Admin\Entity\AdminRole;
99
use Api\Admin\Repository\AdminRoleRepository;
10+
use Api\App\Exception\BadRequestException;
1011
use Api\App\Exception\NotFoundException;
1112
use Api\App\Message;
1213
use Dot\DependencyInjection\Attribute\Inject;
@@ -34,8 +35,22 @@ public function findOneBy(array $params = []): AdminRole
3435
return $role;
3536
}
3637

38+
/**
39+
* @throws BadRequestException
40+
*/
3741
public function getAdminRoles(array $params = []): AdminRoleCollection
3842
{
43+
$values = [
44+
'role.name',
45+
'role.created',
46+
'role.updated',
47+
];
48+
49+
$params['order'] = $params['order'] ?? 'role.created';
50+
if (! in_array($params['order'], $values)) {
51+
throw (new BadRequestException())->setMessages([sprintf(Message::INVALID_VALUE, 'order')]);
52+
}
53+
3954
return $this->adminRoleRepository->getAdminRoles($params);
4055
}
4156
}

‎src/Admin/src/Service/AdminRoleServiceInterface.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
use Api\Admin\Collection\AdminRoleCollection;
88
use Api\Admin\Entity\AdminRole;
9+
use Api\App\Exception\BadRequestException;
910
use Api\App\Exception\NotFoundException;
1011

1112
interface AdminRoleServiceInterface
@@ -15,5 +16,8 @@ interface AdminRoleServiceInterface
1516
*/
1617
public function findOneBy(array $params = []): AdminRole;
1718

19+
/**
20+
* @throws BadRequestException
21+
*/
1822
public function getAdminRoles(array $params = []): AdminRoleCollection;
1923
}

‎src/Admin/src/Service/AdminService.php‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,25 @@ public function findOneBy(array $params = []): Admin
9191
return $admin;
9292
}
9393

94+
/**
95+
* @throws BadRequestException
96+
*/
9497
public function getAdmins(array $params = []): AdminCollection
9598
{
99+
$values = [
100+
'admin.identity',
101+
'admin.firstName',
102+
'admin.lastName',
103+
'admin.status',
104+
'admin.created',
105+
'admin.updated',
106+
];
107+
108+
$params['order'] = $params['order'] ?? 'admin.created';
109+
if (! in_array($params['order'], $values)) {
110+
throw (new BadRequestException())->setMessages([sprintf(Message::INVALID_VALUE, 'order')]);
111+
}
112+
96113
return $this->adminRepository->getAdmins($params);
97114
}
98115

‎src/Admin/src/Service/AdminServiceInterface.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ public function exists(string $identity = ''): bool;
2727
*/
2828
public function findOneBy(array $params = []): Admin;
2929

30+
/**
31+
* @throws BadRequestException
32+
*/
3033
public function getAdmins(array $params = []): AdminCollection;
3134

3235
/**

‎src/App/src/OpenAPI.php‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@
6060
type: 'object',
6161
)
6262
),
63-
tags: ['Error Report'],
63+
tags: ['ErrorReport'],
6464
responses: [
6565
new OA\Response(
6666
response: StatusCodeInterface::STATUS_CREATED,
@@ -107,7 +107,7 @@
107107
type: 'object',
108108
),
109109
),
110-
tags: ['Access Token'],
110+
tags: ['AccessToken'],
111111
responses: [
112112
new OA\Response(
113113
response: StatusCodeInterface::STATUS_OK,
@@ -143,7 +143,7 @@
143143
type: 'object',
144144
),
145145
),
146-
tags: ['Access Token'],
146+
tags: ['AccessToken'],
147147
responses: [
148148
new OA\Response(
149149
response: StatusCodeInterface::STATUS_OK,
@@ -228,6 +228,7 @@
228228

229229
#[OA\Schema(
230230
schema: 'Collection',
231+
description: 'Base collection providing common structure to be extended by entity-specific collections',
231232
properties: [
232233
new OA\Property(property: '_total_items', type: 'integer', example: 1),
233234
new OA\Property(property: '_page', type: 'integer', example: 1),

‎src/User/src/Handler/AccountResetPasswordHandler.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
use Api\User\Service\UserServiceInterface;
1717
use Dot\DependencyInjection\Attribute\Inject;
1818
use Dot\Mail\Exception\MailException;
19+
use Fig\Http\Message\StatusCodeInterface;
1920
use Mezzio\Hal\HalResponseFactory;
2021
use Mezzio\Hal\ResourceGenerator;
2122
use Psr\Http\Message\ResponseInterface;
@@ -123,6 +124,6 @@ public function post(ServerRequestInterface $request): ResponseInterface
123124
$this->userService->updateUser($user->createResetPassword());
124125
$this->userService->sendResetPasswordRequestedMail($user);
125126

126-
return $this->infoResponse(Message::MAIL_SENT_RESET_PASSWORD);
127+
return $this->infoResponse(Message::MAIL_SENT_RESET_PASSWORD, StatusCodeInterface::STATUS_CREATED);
127128
}
128129
}

0 commit comments

Comments
 (0)