diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitBadgesApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitBadgesApiController.php index 55cac8eb6..fc549c17c 100644 --- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitBadgesApiController.php +++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitBadgesApiController.php @@ -1,4 +1,7 @@ -summit_repository; } + // OpenAPI Documentation + + #[OA\Get( + path: '/api/v1/summits/{id}/badges', + summary: 'Get all attendee badges for a summit', + description: 'Retrieves a paginated list of attendee badges for a specific summit. Badges are issued to attendees and contain ticket information, badge type, printing details, and feature assignments (ribbons, special access indicators, etc.).', + security: [['Bearer' => [SummitScopes::ReadAllSummitData]]], + tags: ['Summit Badges'], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + description: 'Summit ID', + schema: new OA\Schema(type: 'integer') + ), + 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 fields: owner_first_name, owner_last_name, owner_full_name, owner_email, ticket_number, order_number (all support =@, ==). Operators: == (equals), =@ (contains)', + style: 'form', + explode: true, + schema: new OA\Schema( + type: 'array', + items: new OA\Items(type: 'string', example: 'owner_email==john@example.com') + ) + ), + new OA\Parameter( + name: 'order', + in: 'query', + required: false, + description: 'Order by field(s). Available fields: id, ticket_number, order_number, created. Use "-" prefix for descending order.', + schema: new OA\Schema(type: 'string', example: 'created') + ), + new OA\Parameter( + name: 'expand', + in: 'query', + required: false, + description: 'Expand relationships. Available: ticket, type, features', + schema: new OA\Schema(type: 'string', example: 'ticket,type,features') + ), + ], + responses: [ + new OA\Response( + response: 200, + description: 'Attendee badges retrieved successfully', + content: new OA\JsonContent(ref: '#/components/schemas/PaginatedSummitAttendeeBadgesResponse') + ), + 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"), + ] + )] + /** * @param $summit_id * @return mixed @@ -103,6 +181,61 @@ function(){ ); } + #[OA\Get( + path: '/api/v1/summits/{id}/badges/csv', + summary: 'Export all attendee badges for a summit to CSV', + description: 'Exports a CSV file containing all attendee badges for a specific summit. Supports the same filtering and ordering capabilities as the standard list endpoint.', + security: [['oauth2_security_scope' => [SummitScopes::ReadAllSummitData]]], + tags: ['Summit Badges'], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + description: 'Summit ID', + schema: new OA\Schema(type: 'integer') + ), + new OA\Parameter( + name: 'filter[]', + in: 'query', + required: false, + description: 'Filter expressions. Format: fieldvalue. Available fields: owner_first_name, owner_last_name, owner_full_name, owner_email, ticket_number, order_number (all support =@, ==)', + style: 'form', + explode: true, + schema: new OA\Schema( + type: 'array', + items: new OA\Items(type: 'string', example: 'owner_email=@example.com') + ) + ), + new OA\Parameter( + name: 'order', + in: 'query', + required: false, + description: 'Order by field(s). Available fields: id, ticket_number, order_number, created', + schema: new OA\Schema(type: 'string', example: '-created') + ), + ], + responses: [ + new OA\Response( + response: 200, + description: 'CSV file generated successfully', + content: new OA\MediaType( + mediaType: 'text/csv', + schema: new OA\Schema( + type: 'string', + format: 'binary' + ) + ) + ), + 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"), + ] + )] + /** * @param $summit_id * @return mixed @@ -163,4 +296,4 @@ function(){ -} \ No newline at end of file +} diff --git a/app/Swagger/SummitSchemas.php b/app/Swagger/SummitSchemas.php index 6b3e2f895..50d89a5f8 100644 --- a/app/Swagger/SummitSchemas.php +++ b/app/Swagger/SummitSchemas.php @@ -4,4 +4,50 @@ use OpenApi\Attributes as OA; -// +// Summit Attendee Badges + +#[OA\Schema( + schema: 'SummitAttendeeBadge', + type: 'object', + properties: [ + new OA\Property(property: 'id', type: 'integer', example: 1), + new OA\Property(property: 'print_date', type: 'integer', nullable: true, example: 1633024800, description: 'Unix timestamp of when the badge was printed'), + new OA\Property(property: 'qr_code', type: 'string', nullable: true, example: 'QR123456789'), + new OA\Property(property: 'is_void', type: 'boolean', example: false, description: 'Whether the badge has been voided'), + new OA\Property(property: 'printed_times', type: 'integer', example: 2, description: 'Number of times this badge has been printed'), + ], + anyOf: [ + new OA\Property(property: 'ticket_id', type: 'integer', example: 123, description: 'Associated ticket ID'), + new OA\Property(property: 'ticket', type: 'Ticket'), + new OA\Property(property: 'type_id', type: 'integer', example: 5, description: 'Badge type ID'), + new OA\Property(property: 'type', type: 'BadgeType'), + new OA\Property(property: 'print_excerpt', type: 'string', example: 'John Doe - Speaker', description: 'Short text excerpt for printing'), + new OA\Property( + property: 'features', + type: 'array', + description: 'Array of feature IDs assigned to this badge (use expand=features for full details)', + items: new OA\Items(type: 'integer'), + example: [1, 2, 3] + ), + ], +)] +class SummitAttendeeBadgeSchema {} + +#[OA\Schema( + schema: 'PaginatedSummitAttendeeBadgesResponse', + allOf: [ + new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'), + new OA\Schema( + type: 'object', + properties: [ + new OA\Property( + property: 'data', + type: 'array', + items: new OA\Items(ref: '#/components/schemas/SummitAttendeeBadge') + ) + ] + ) + ] +)] +class PaginatedSummitAttendeeBadgesResponseSchema {} +