Skip to content

Commit 089de6d

Browse files
matiasperrone-exomatiasperrone-exo
committed
feat: Add OpenAPI documentation on controller OAuth2UserApiController v2 routes
1 parent 2c2445e commit 089de6d

File tree

5 files changed

+196
-0
lines changed

5 files changed

+196
-0
lines changed

‎app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,11 @@
3737
use OAuth2\ResourceServer\IUserService;
3838
use Utils\Http\HttpContentType;
3939
use Utils\Services\ILogService;
40+
use App\libs\OAuth2\IUserScopes;
4041
use Exception;
42+
use OpenApi\Attributes as OA;
4143
use OpenId\Services\IUserService as IOpenIdUserService;
44+
use Symfony\Component\HttpFoundation\Response as HttpResponse;
4245
/**
4346
* Class OAuth2UserApiController
4447
* @package App\Http\Controllers\Api\OAuth2
@@ -336,6 +339,49 @@ public function get($id)
336339
* @param $id
337340
* @return \Illuminate\Http\JsonResponse|mixed
338341
*/
342+
#[OA\Get(
343+
path: '/api/v2/users/{id}',
344+
summary: 'Get a user by ID',
345+
description: 'Get a user by ID (only for accounts of type "SERVICE")',
346+
operationId: 'getUserByIdV2',
347+
tags: ['Users'],
348+
security: [
349+
['OAuth2UserSecurity' => [
350+
IUserScopes::ReadAll,
351+
]],
352+
],
353+
parameters: [
354+
new OA\Parameter(
355+
name: 'id',
356+
description: 'User ID',
357+
in: 'path',
358+
required: true,
359+
schema: new OA\Schema(type: 'integer')
360+
),
361+
new OA\Parameter(
362+
name: 'expand',
363+
description: 'Expand relations: groups',
364+
in: 'query',
365+
required: false,
366+
schema: new OA\Schema(type: 'string')
367+
),
368+
],
369+
responses: [
370+
new OA\Response(
371+
response: HttpResponse::HTTP_OK,
372+
description: 'OK',
373+
content: new OA\JsonContent(ref: '#/components/schemas/User')
374+
),
375+
new OA\Response(
376+
response: HttpResponse::HTTP_NOT_FOUND,
377+
description: 'Not Found'
378+
),
379+
new OA\Response(
380+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
381+
description: 'Server Error'
382+
),
383+
]
384+
)]
339385
public function getV2($id)
340386
{
341387
return $this->processRequest(function() use($id) {

‎app/Swagger/Models/BaseUserSchema.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 OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'BaseUser',
9+
title: 'Base User',
10+
description: 'Base User serialized representation',
11+
type: 'object',
12+
allOf: [
13+
new OA\Schema(ref: '#/components/schemas/Base'),
14+
new OA\Schema(
15+
type: 'object',
16+
properties: [
17+
new OA\Property(property: 'first_name', type: 'string', description: 'First name', example: 'John'),
18+
new OA\Property(property: 'last_name', type: 'string', description: 'Last name', example: 'Doe'),
19+
new OA\Property(property: 'pic', type: 'string', format: 'uri', description: 'Profile picture URL'),
20+
]
21+
)
22+
]
23+
)]
24+
class BaseUserSchema
25+
{
26+
}

‎app/Swagger/Models/GroupSchema.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'Group',
9+
title: 'Group',
10+
description: 'Group serialized representation',
11+
type: 'object',
12+
allOf: [
13+
new OA\Schema(ref: '#/components/schemas/Base'),
14+
new OA\Schema(
15+
type: 'object',
16+
properties: [
17+
new OA\Property(property: 'name', type: 'string', description: 'Group name'),
18+
new OA\Property(property: 'slug', type: 'string', description: 'Group slug'),
19+
new OA\Property(property: 'active', type: 'boolean', description: 'Whether the group is active'),
20+
new OA\Property(property: 'default', type: 'boolean', description: 'Whether the group is a default group'),
21+
]
22+
)
23+
]
24+
)]
25+
class GroupSchema
26+
{
27+
}

‎app/Swagger/Models/UserSchema.php‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'User',
9+
title: 'User',
10+
description: 'User serialized representation (private)',
11+
type: 'object',
12+
allOf: [
13+
new OA\Schema(ref: '#/components/schemas/BaseUser'),
14+
new OA\Schema(
15+
type: 'object',
16+
properties: [
17+
new OA\Property(property: 'email', type: 'string', format: 'email', description: 'Primary email address'),
18+
new OA\Property(property: 'identifier', type: 'string', description: 'User unique identifier string'),
19+
new OA\Property(property: 'email_verified', type: 'boolean', description: 'Whether the primary email is verified'),
20+
new OA\Property(property: 'bio', type: 'string', nullable: true, description: 'User biography'),
21+
new OA\Property(property: 'address1', type: 'string', description: 'Address line 1'),
22+
new OA\Property(property: 'address2', type: 'string', nullable: true, description: 'Address line 2'),
23+
new OA\Property(property: 'city', type: 'string', description: 'City'),
24+
new OA\Property(property: 'state', type: 'string', description: 'State or province'),
25+
new OA\Property(property: 'post_code', type: 'string', description: 'Postal code'),
26+
new OA\Property(property: 'country_iso_code', type: 'string', description: 'ISO country code'),
27+
new OA\Property(property: 'second_email', type: 'string', format: 'email', nullable: true, description: 'Secondary email address'),
28+
new OA\Property(property: 'third_email', type: 'string', format: 'email', nullable: true, description: 'Tertiary email address'),
29+
new OA\Property(property: 'gender', type: 'string', nullable: true, description: 'Gender'),
30+
new OA\Property(property: 'gender_specify', type: 'string', nullable: true, description: 'Gender specification'),
31+
new OA\Property(property: 'statement_of_interest', type: 'string', nullable: true, description: 'Statement of interest'),
32+
new OA\Property(property: 'irc', type: 'string', nullable: true, description: 'IRC handle'),
33+
new OA\Property(property: 'linked_in_profile', type: 'string', nullable: true, description: 'LinkedIn profile URL'),
34+
new OA\Property(property: 'github_user', type: 'string', nullable: true, description: 'GitHub username'),
35+
new OA\Property(property: 'wechat_user', type: 'string', nullable: true, description: 'WeChat username'),
36+
new OA\Property(property: 'twitter_name', type: 'string', nullable: true, description: 'Twitter handle'),
37+
new OA\Property(property: 'language', type: 'string', nullable: true, description: 'Preferred language'),
38+
new OA\Property(property: 'birthday', type: 'integer', nullable: true, description: 'Date of birth (epoch)'),
39+
new OA\Property(property: 'phone_number', type: 'string', nullable: true, description: 'Phone number'),
40+
new OA\Property(property: 'company', type: 'string', nullable: true, description: 'Company name'),
41+
new OA\Property(property: 'job_title', type: 'string', nullable: true, description: 'Job title'),
42+
new OA\Property(property: 'spam_type', type: 'string', description: 'Spam classification', enum: ['None', 'Spam', 'Ham']),
43+
new OA\Property(property: 'last_login_date', type: 'integer', nullable: true, description: 'Last login date (epoch)'),
44+
new OA\Property(property: 'active', type: 'boolean', description: 'Whether the user account is active'),
45+
new OA\Property(property: 'public_profile_show_photo', type: 'boolean', description: 'Show photo in public profile'),
46+
new OA\Property(property: 'public_profile_show_fullname', type: 'boolean', description: 'Show full name in public profile'),
47+
new OA\Property(property: 'public_profile_show_email', type: 'boolean', description: 'Show email in public profile'),
48+
new OA\Property(property: 'public_profile_show_social_media_info', type: 'boolean', description: 'Show social media info in public profile'),
49+
new OA\Property(property: 'public_profile_show_bio', type: 'boolean', description: 'Show bio in public profile'),
50+
new OA\Property(property: 'public_profile_allow_chat_with_me', type: 'boolean', description: 'Allow chat in public profile'),
51+
new OA\Property(property: 'public_profile_show_telephone_number', type: 'boolean', description: 'Show telephone in public profile'),
52+
new OA\Property(
53+
property: 'groups',
54+
type: 'array',
55+
items: new OA\Items(oneOf: [
56+
new OA\Schema(type: 'string', description: 'Group slug (when not expanded)'),
57+
new OA\Schema(ref: '#/components/schemas/Group', description:'Group object (when expanded)'),
58+
]),
59+
description: 'User groups (expandable with expand=groups)'
60+
),
61+
]
62+
)
63+
]
64+
)]
65+
class UserSchema
66+
{
67+
}

‎app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.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 App\libs\OAuth2\IUserScopes;
6+
use OpenApi\Attributes as OA;
7+
8+
#[
9+
OA\SecurityScheme(
10+
type: 'oauth2',
11+
securityScheme: 'OAuth2UserSecurity',
12+
description: 'OAuth2 security scheme for user-related API endpoints',
13+
flows: [
14+
new OA\Flow(
15+
flow: 'authorizationCode',
16+
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
17+
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
18+
scopes: [
19+
IUserScopes::ReadAll => 'Read All Users Data',
20+
IUserScopes::MeWrite => 'Write current user data',
21+
IUserScopes::Write => 'Write Users Data',
22+
IUserScopes::UserGroupWrite => 'Manage User Group assignments',
23+
],
24+
),
25+
],
26+
)
27+
]
28+
class OAuth2UserApiControllerSecuritySchema
29+
{
30+
}

0 commit comments

Comments
 (0)