diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitMediaFileTypeApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitMediaFileTypeApiController.php index 4fe2a7105..9c806e624 100644 --- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitMediaFileTypeApiController.php +++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitMediaFileTypeApiController.php @@ -1,4 +1,7 @@ -repository = $repository; } + // OpenAPI Documentation + + #[OA\Get( + path: '/api/v1/summit-media-file-types', + operationId: 'getAllSummitMediaFileTypes', + summary: 'Get all summit media file types', + description: 'Retrieves a paginated list of summit media file types. Media file types define categories of files that can be uploaded to summits (e.g., presentations, videos, documents) along with their allowed file extensions.', + x: [ + 'required-groups' => [ + IGroup::SuperAdmins, + IGroup::Administrators, + IGroup::SummitAdministrators, + ] + ], + security: [['summit_media_file_type_oauth2' => [ + SummitScopes::ReadSummitMediaFileTypes + ]]], + tags: ['Summit Media File Types'], + parameters: [ + new OA\Parameter( + name: 'page', + in: 'query', + required: false, + description: 'Page number for pagination', + schema: new OA\Schema(type: 'integer', example: 1) + ), + new OA\Parameter( + name: 'per_page', + in: 'query', + required: false, + description: 'Items per page', + schema: new OA\Schema(type: 'integer', example: 10, maximum: 100) + ), + new OA\Parameter( + name: 'filter[]', + in: 'query', + required: false, + description: 'Filter expressions. Format: fieldvalue. Available field: name (=@, ==). Operators: == (equals), =@ (starts with)', + style: 'form', + explode: true, + schema: new OA\Schema( + type: 'array', + items: new OA\Items(type: 'string', example: 'name@@presentation') + ) + ), + new OA\Parameter( + name: 'order', + in: 'query', + required: false, + description: 'Order by field(s). Available fields: name, id. Use "-" prefix for descending order.', + schema: new OA\Schema(type: 'string', example: 'name') + ), + ], + responses: [ + new OA\Response( + response: 200, + description: 'Media file types retrieved successfully', + content: new OA\JsonContent(ref: '#/components/schemas/PaginatedSummitMediaFileTypesResponse') + ), + new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"), + ] + )] + + #[OA\Get( + path: '/api/v1/summit-media-file-types/{id}', + operationId: 'getSummitMediaFileType', + summary: 'Get a summit media file type by ID', + description: 'Retrieves detailed information about a specific summit media file type.', + x: [ + 'required-groups' => [ + IGroup::SuperAdmins, + IGroup::Administrators, + IGroup::SummitAdministrators, + ] + ], + security: [['summit_media_file_type_oauth2' => [ + SummitScopes::ReadSummitMediaFileTypes + ]]], + tags: ['Summit Media File Types'], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + description: 'Summit Media File Type ID', + schema: new OA\Schema(type: 'integer') + ), + ], + responses: [ + new OA\Response( + response: 200, + description: 'Media file type retrieved successfully', + content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileType') + ), + new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"), + ] + )] + + #[OA\Post( + path: '/api/v1/summit-media-file-types', + operationId: 'createSummitMediaFileType', + summary: 'Create a new summit media file type', + description: 'Creates a new summit media file type with specified name, description, and allowed file extensions.', + x: [ + 'required-groups' => [ + IGroup::SuperAdmins, + IGroup::Administrators, + IGroup::SummitAdministrators, + ] + ], + security: [['summit_media_file_type_oauth2' => [ + SummitScopes::WriteSummitMediaFileTypes + ]]], + tags: ['Summit Media File Types'], + requestBody: new OA\RequestBody( + required: true, + content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileTypeCreateRequest') + ), + responses: [ + new OA\Response( + response: 201, + description: 'Media file type created successfully', + content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileType') + ), + new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"), + ] + )] + + #[OA\Put( + path: '/api/v1/summit-media-file-types/{id}', + operationId: 'updateSummitMediaFileType', + summary: 'Update a summit media file type', + description: 'Updates an existing summit media file type.', + x: [ + 'required-groups' => [ + IGroup::SuperAdmins, + IGroup::Administrators, + IGroup::SummitAdministrators, + ] + ], + security: [['summit_media_file_type_oauth2' => [ + SummitScopes::WriteSummitMediaFileTypes + ]]], + tags: ['Summit Media File Types'], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + description: 'Summit Media File Type ID', + schema: new OA\Schema(type: 'integer') + ), + ], + requestBody: new OA\RequestBody( + required: true, + content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileTypeUpdateRequest') + ), + responses: [ + new OA\Response( + response: 200, + description: 'Media file type updated successfully', + content: new OA\JsonContent(ref: '#/components/schemas/SummitMediaFileType') + ), + new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"), + ] + )] + + #[OA\Delete( + path: '/api/v1/summit-media-file-types/{id}', + operationId: 'deleteSummitMediaFileType', + summary: 'Delete a summit media file type', + description: 'Deletes an existing summit media file type. System-defined types cannot be deleted.', + x: [ + 'required-groups' => [ + IGroup::SuperAdmins, + IGroup::Administrators, + IGroup::SummitAdministrators, + ] + ], + security: [['summit_media_file_type_oauth2' => [ + SummitScopes::WriteSummitMediaFileTypes + ]]], + tags: ['Summit Media File Types'], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + description: 'Summit Media File Type ID', + schema: new OA\Schema(type: 'integer') + ), + ], + responses: [ + new OA\Response( + response: 204, + description: 'Media file type deleted successfully' + ), + new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"), + ] + )] /** * @inheritDoc @@ -139,4 +373,4 @@ function(){ } ); } -} \ No newline at end of file +} diff --git a/app/Swagger/Security/SummitMediaFileTypeAuthSchema.php b/app/Swagger/Security/SummitMediaFileTypeAuthSchema.php new file mode 100644 index 000000000..032233c54 --- /dev/null +++ b/app/Swagger/Security/SummitMediaFileTypeAuthSchema.php @@ -0,0 +1,26 @@ + 'Read Summit Media File Types', + SummitScopes::WriteSummitMediaFileTypes => 'Write Summit Media File Types', + ], + ), + ], + ) +] +class SummitMediaFileTypeAuthSchema{} diff --git a/app/Swagger/SummitSchemas.php b/app/Swagger/SummitSchemas.php index 6b3e2f895..3803ca47b 100644 --- a/app/Swagger/SummitSchemas.php +++ b/app/Swagger/SummitSchemas.php @@ -5,3 +5,77 @@ use OpenApi\Attributes as OA; // + +#[OA\Schema( + schema: 'SummitMediaFileType', + type: 'object', + properties: [ + new OA\Property(property: 'id', type: 'integer', example: 1), + new OA\Property(property: 'created', type: 'integer', format: 'int64', example: 1633024800), + new OA\Property(property: 'last_edited', type: 'integer', format: 'int64', example: 1633024800), + new OA\Property(property: 'name', type: 'string', example: 'Presentation'), + new OA\Property(property: 'description', type: 'string', example: 'Presentation files for events'), + new OA\Property(property: 'is_system_defined', type: 'boolean', example: false), + new OA\Property( + property: 'allowed_extensions', + type: 'array', + items: new OA\Items(type: 'string'), + example: ['pdf', 'ppt', 'pptx'] + ), + ] +)] +class SummitMediaFileTypeSchema {} + +#[OA\Schema( + schema: 'PaginatedSummitMediaFileTypesResponse', + type: 'object', + allOf: [ + new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'), + new OA\Schema( + properties: [ + new OA\Property( + property: 'data', + type: 'array', + items: new OA\Items(ref: '#/components/schemas/SummitMediaFileType') + ) + ] + ) + ] +)] +class PaginatedSummitMediaFileTypesResponseSchema {} + +#[OA\Schema( + schema: 'SummitMediaFileTypeCreateRequest', + required: ['name', 'allowed_extensions'], + type: 'object', + properties: [ + new OA\Property(property: 'name', type: 'string', maxLength: 255, example: 'Presentation'), + new OA\Property(property: 'description', type: 'string', maxLength: 255, example: 'Presentation files for events'), + new OA\Property( + property: 'allowed_extensions', + type: 'array', + items: new OA\Items(type: 'string'), + example: ['pdf', 'ppt', 'pptx'], + description: 'Array of allowed file extensions' + ), + ] +)] +class SummitMediaFileTypeCreateRequestSchema {} + +#[OA\Schema( + schema: 'SummitMediaFileTypeUpdateRequest', + required: ['allowed_extensions'], + type: 'object', + properties: [ + new OA\Property(property: 'name', type: 'string', maxLength: 255, example: 'Presentation'), + new OA\Property(property: 'description', type: 'string', maxLength: 255, example: 'Presentation files for events'), + new OA\Property( + property: 'allowed_extensions', + type: 'array', + items: new OA\Items(type: 'string'), + example: ['pdf', 'ppt', 'pptx'], + description: 'Array of allowed file extensions' + ), + ] +)] +class SummitMediaFileTypeUpdateRequestSchema {}