Skip to content

Commit 113642d

Browse files
matiasperrone-exosmarcetmatiasperrone
authored
Feature | Extend Swagger Coverage for controller OAuth2AuditLogController (#367)
* 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: Move schemas to the proper schemas file * fix: conflicts issue with main * fix: Change "namespace" word positioning * fix: security scope * fix: Add security schema * chore: Move the security schema for the controller to its own file --------- Co-authored-by: smarcet <smarcet@gmail.com> Co-authored-by: Matias Perrone <github@matiasperrone.com>
1 parent 60d5b97 commit 113642d

File tree

3 files changed

+139
-3
lines changed

3 files changed

+139
-3
lines changed

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

Lines changed: 79 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
<?php namespace App\Http\Controllers;
1+
<?php
2+
3+
namespace App\Http\Controllers;
4+
25
/**
36
* Copyright 2022 OpenStack Foundation
47
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,12 +16,15 @@
1316
**/
1417

1518
use App\Models\Foundation\Main\Repositories\IAuditLogRepository;
19+
use App\Security\SummitScopes;
20+
use Illuminate\Http\Response;
1621
use models\main\SummitAttendeeBadgeAuditLog;
1722
use models\main\SummitAuditLog;
1823
use models\main\SummitEventAuditLog;
1924
use models\oauth2\IResourceServerContext;
2025
use models\summit\SummitAttendeeBadge;
2126
use ModelSerializers\SerializerRegistry;
27+
use OpenApi\Attributes as OA;
2228

2329
/**
2430
* Class OAuth2AuditLogController
@@ -46,6 +52,77 @@ public function __construct
4652
/**
4753
* @return mixed
4854
*/
55+
#[OA\Get(
56+
path: "/api/v1/audit-logs",
57+
description: "Get all audit logs with filtering capabilities. Requires OAuth2 authentication with appropriate scope.",
58+
summary: 'Get all audit logs',
59+
operationId: 'getAllAuditLogs',
60+
tags: ['Audit Logs'],
61+
security: [['audit_logs_oauth2' => [
62+
SummitScopes::ReadAuditLogs,
63+
]]],
64+
parameters: [
65+
new OA\Parameter(
66+
name: 'access_token',
67+
in: 'query',
68+
required: false,
69+
description: 'OAuth2 access token (alternative to Authorization: Bearer)',
70+
schema: new OA\Schema(type: 'string', example: 'eyJhbGciOi...')
71+
),
72+
new OA\Parameter(
73+
name: 'page',
74+
in: 'query',
75+
required: false,
76+
description: 'Page number for pagination',
77+
schema: new OA\Schema(type: 'integer', example: 1)
78+
),
79+
new OA\Parameter(
80+
name: 'per_page',
81+
in: 'query',
82+
required: false,
83+
description: 'Items per page',
84+
schema: new OA\Schema(type: 'integer', example: 10, maximum: 100)
85+
),
86+
new OA\Parameter(
87+
name: 'filter[]',
88+
in: 'query',
89+
required: false,
90+
description: 'Filter expressions. Format: field<op>value. Available fields: class_name (required, ==), user_id (==), summit_id (==), event_id (==), entity_id (==), user_email (==, =@, @@), user_full_name (==, =@, @@), action (=@, @@), metadata (==, =@, @@), created (==, >, <, >=, <=, []). class_name must be one of: SummitAuditLog, SummitEventAuditLog, SummitAttendeeBadgeAuditLog',
91+
style: 'form',
92+
explode: true,
93+
schema: new OA\Schema(
94+
type: 'array',
95+
items: new OA\Items(type: 'string', example: 'class_name==SummitAuditLog')
96+
)
97+
),
98+
new OA\Parameter(
99+
name: 'order',
100+
in: 'query',
101+
required: false,
102+
description: 'Order by field(s). Available fields: id, user_id, event_id, entity_id, created, user_email, user_full_name, metadata. Use "-" prefix for descending order.',
103+
schema: new OA\Schema(type: 'string', example: '-created')
104+
),
105+
new OA\Parameter(
106+
name: 'expand',
107+
in: 'query',
108+
required: false,
109+
description: 'Comma-separated list of related resources to include. Available relations: user, summit',
110+
schema: new OA\Schema(type: 'string', example: 'user,summit')
111+
),
112+
],
113+
responses: [
114+
new OA\Response(
115+
response: 200,
116+
description: 'Success - Returns paginated list of audit logs',
117+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedAuditLogsResponse')
118+
),
119+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request - Invalid parameters"),
120+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized - Invalid or missing access token"),
121+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - Insufficient permissions"),
122+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error - Missing required filters"),
123+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error")
124+
]
125+
)]
49126
public function getAll(){
50127

51128
return $this->_getAll(
@@ -97,4 +174,4 @@ function () {
97174
}
98175
);
99176
}
100-
}
177+
}

‎app/Swagger/AuditSchemas.php‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,38 @@
44

55
use OpenApi\Attributes as OA;
66

7-
//
7+
#[OA\Schema(
8+
schema: 'AuditLog',
9+
type: 'object',
10+
properties: [
11+
new OA\Property(property: 'id', type: 'integer', example: 1, description: 'Unique identifier'),
12+
new OA\Property(property: 'created', type: 'integer', example: 1630500518, description: 'Creation timestamp (Unix epoch)'),
13+
new OA\Property(property: 'last_edited', type: 'integer', example: 1630500518, description: 'Last modification timestamp (Unix epoch)'),
14+
new OA\Property(property: 'class_name', type: 'string', example: 'SummitAuditLog', description: 'Audit log type: SummitAuditLog, SummitEventAuditLog, or SummitAttendeeBadgeAuditLog'),
15+
new OA\Property(property: 'action', type: 'string', example: 'UPDATED', description: 'Action performed (e.g., CREATED, UPDATED, DELETED)'),
16+
new OA\Property(property: 'metadata', type: 'string', example: 'Additional audit information', description: 'Metadata about the audit action', nullable: true),
17+
new OA\Property(property: 'user_id', type: 'integer', example: 123, description: 'ID of the user who performed the action'),
18+
new OA\Property(property: 'summit_id', type: 'integer', example: 45, description: 'Summit ID (for SummitAuditLog, SummitEventAuditLog, SummitAttendeeBadgeAuditLog)', nullable: true),
19+
new OA\Property(property: 'event_id', type: 'integer', example: 789, description: 'Event ID (for SummitEventAuditLog)', nullable: true),
20+
new OA\Property(property: 'attendee_badge_id', type: 'integer', example: 456, description: 'Attendee Badge ID (for SummitAttendeeBadgeAuditLog)', nullable: true),
21+
]
22+
)]
23+
class AuditLogSchema {}
24+
25+
#[OA\Schema(
26+
schema: 'PaginatedAuditLogsResponse',
27+
allOf: [
28+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
29+
new OA\Schema(
30+
type: 'object',
31+
properties: [
32+
new OA\Property(
33+
property: 'data',
34+
type: 'array',
35+
items: new OA\Items(ref: '#/components/schemas/AuditLog')
36+
)
37+
]
38+
)
39+
]
40+
)]
41+
class PaginatedAuditLogsResponseSchema {}

‎app/Swagger/Security/AuditLogAuthSchema.php‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<?php
2+
3+
namespace App\Swagger\Schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
use App\Security\SummitScopes;
7+
8+
#[OA\SecurityScheme(
9+
type: 'oauth2',
10+
securityScheme: 'audit_logs_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::ReadAuditLogs,
18+
],
19+
),
20+
],
21+
)
22+
]
23+
class AuditLogAuthSchema
24+
{
25+
}

0 commit comments

Comments
 (0)