Feature | Extend Swagger Coverage for controller OAuth2SummitBadgesApiController

app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitBadgesApiController.php

@@ -1,4 +1,7 @@
-<?php namespace App\Http\Controllers;
+<?php
+
+namespace App\Http\Controllers;
+
 /**
  * Copyright 2019 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,9 +15,12 @@
  * limitations under the License.
  **/
 use App\Models\Foundation\Summit\Repositories\ISummitAttendeeBadgeRepository;
+use App\Security\SummitScopes;
 use models\oauth2\IResourceServerContext;
 use models\summit\ISummitRepository;
 use ModelSerializers\SerializerRegistry;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response;
 use utils\Filter;
 use utils\FilterElement;
 
@@ -37,8 +43,7 @@ public function __construct
         ISummitAttendeeBadgeRepository $repository,
         ISummitRepository $summit_repository,
         IResourceServerContext $resource_server_context
-    )
-    {
+    ) {
         parent::__construct($resource_server_context);
         $this->repository = $repository;
         $this->summit_repository = $summit_repository;
@@ -52,109 +57,240 @@ protected function getSummitRepository(): ISummitRepository
         return $this->summit_repository;
     }
 
+    // OpenAPI Documentation
+
+    #[OA\Get(
+        path: '/api/v1/summits/{id}/badges',
+        operationId: 'getAllBySummit',
+        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: [['summit_badges_api_oauth2' => [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: field<op>value. 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
      */
-    public function getAllBySummit($summit_id){
+    public function getAllBySummit($summit_id)
+    {
 
         $summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
-        if (is_null($summit)) return $this->error404();
+        if (is_null($summit))
+            return $this->error404();
 
         return $this->_getAll(
-            function(){
+            function () {
                 return [
-                    'owner_first_name'           => ['=@', '=='],
-                    'owner_last_name'            => ['=@', '=='],
-                    'owner_full_name'            => ['=@', '=='],
-                    'owner_email'                => ['=@', '=='],
-                    'ticket_number'              => ['=@', '=='],
-                    'order_number'               => ['=@', '=='],
+                    'owner_first_name' => ['=@', '=='],
+                    'owner_last_name' => ['=@', '=='],
+                    'owner_full_name' => ['=@', '=='],
+                    'owner_email' => ['=@', '=='],
+                    'ticket_number' => ['=@', '=='],
+                    'order_number' => ['=@', '=='],
                 ];
             },
-            function(){
+            function () {
                 return [
-                    'owner_first_name'           => 'sometimes|string',
-                    'owner_last_name'            => 'sometimes|string',
-                    'owner_full_name'            => 'sometimes|string',
-                    'owner_email'                => 'sometimes|string',
-                    'ticket_number'               => 'sometimes|string',
-                    'order_number'                => 'sometimes|string',
+                    'owner_first_name' => 'sometimes|string',
+                    'owner_last_name' => 'sometimes|string',
+                    'owner_full_name' => 'sometimes|string',
+                    'owner_email' => 'sometimes|string',
+                    'ticket_number' => 'sometimes|string',
+                    'order_number' => 'sometimes|string',
                 ];
             },
-            function()
-            {
+            function () {
                 return [
                     'id',
                     'ticket_number',
                     'order_number',
                     'created'
                 ];
             },
-            function($filter) use($summit){
-                if($filter instanceof Filter){
+            function ($filter) use ($summit) {
+                if ($filter instanceof Filter) {
                     $filter->addFilterCondition(FilterElement::makeEqual('summit_id', $summit->getId()));
                 }
                 return $filter;
             },
-            function(){
+            function () {
                 return SerializerRegistry::SerializerType_Private;
             }
         );
     }
 
+    #[OA\Get(
+        path: '/api/v1/summits/{id}/badges/csv',
+        operationId: 'getAllBySummitCSV',
+        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: [['summit_badges_api_oauth2' => [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: field<op>value. 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=@john')
+                )
+            ),
+            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
      */
-    public function getAllBySummitCSV($summit_id){
+    public function getAllBySummitCSV($summit_id)
+    {
 
         $summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
-        if (is_null($summit)) return $this->error404();
+        if (is_null($summit))
+            return $this->error404();
 
         return $this->_getAllCSV(
-            function(){
+            function () {
                 return [
-                    'owner_first_name'           => ['=@', '=='],
-                    'owner_last_name'            => ['=@', '=='],
-                    'owner_full_name'            => ['=@', '=='],
-                    'owner_email'                => ['=@', '=='],
-                    'ticket_number'              => ['=@', '=='],
-                    'order_number'               => ['=@', '=='],
+                    'owner_first_name' => ['=@', '=='],
+                    'owner_last_name' => ['=@', '=='],
+                    'owner_full_name' => ['=@', '=='],
+                    'owner_email' => ['=@', '=='],
+                    'ticket_number' => ['=@', '=='],
+                    'order_number' => ['=@', '=='],
                 ];
             },
-            function(){
+            function () {
                 return [
-                    'owner_first_name'           => 'sometimes|string',
-                    'owner_last_name'            => 'sometimes|string',
-                    'owner_full_name'            => 'sometimes|string',
-                    'owner_email'                => 'sometimes|string',
-                    'ticket_number'               => 'sometimes|string',
-                    'order_number'                => 'sometimes|string',
+                    'owner_first_name' => 'sometimes|string',
+                    'owner_last_name' => 'sometimes|string',
+                    'owner_full_name' => 'sometimes|string',
+                    'owner_email' => 'sometimes|string',
+                    'ticket_number' => 'sometimes|string',
+                    'order_number' => 'sometimes|string',
                 ];
             },
-            function()
-            {
+            function () {
                 return [
                     'id',
                     'ticket_number',
                     'order_number',
                     'created'
                 ];
             },
-            function($filter) use($summit){
-                if($filter instanceof Filter){
+            function ($filter) use ($summit) {
+                if ($filter instanceof Filter) {
                     $filter->addFilterCondition(FilterElement::makeEqual('summit_id', $summit->getId()));
                 }
                 return $filter;
             },
-            function(){
+            function () {
                 return SerializerRegistry::SerializerType_Private;
             },
-            function(){
+            function () {
                 return [];
             },
-            function(){
+            function () {
                 return [];
             },
             'attendees-badges-'
@@ -163,4 +299,4 @@ function(){
 
 
 
-}
+}

app/Swagger/Models/SummitBadgeFeatureTypeSchema.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'SummitBadgeFeatureType',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'created', type: 'integer', example: 1),
+        new OA\Property(property: 'last_edited', type: 'integer', example: 1),
+        new OA\Property(property: 'name', type: 'string'),
+        new OA\Property(property: 'description', type: 'string'),
+        new OA\Property(property: 'template_content', type: 'string'),
+        new OA\Property(property: 'summit_id', type: 'integer'),
+        new OA\Property(property: 'image', type: 'string', format: 'url'),
+    ])
+]
+class SummitBadgeFeatureTypeSchema
+{
+}

app/Swagger/Models/SummitBadgeTypeSchema.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'SummitBadgeType',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'created', type: 'integer', example: 1),
+        new OA\Property(property: 'last_edited', type: 'integer', example: 1),
+        new OA\Property(property: 'name', type: 'string'),
+        new OA\Property(property: 'description', type: 'string'),
+        new OA\Property(property: 'template_content', type: 'string'),
+        new OA\Property(property: 'is_default', type: 'boolean'),
+        new OA\Property(property: 'summit_id', type: 'integer', description: 'Summit ID, use expand=summit for full object details'),
+        new OA\Property(
+            property: 'access_levels',
+            type: 'array',
+            description: 'Array of SummitAccessLevelType IDs, use expand=access_levels for full details',
+            items: new OA\Items(type: 'integer'),
+            example: [1, 2, 3]
+        ),
+        new OA\Property(
+            property: 'badge_features',
+            type: 'array',
+            description: 'Array of SummitBadgeFeatureType IDs, use expand=badge_features for full details',
+            items: new OA\Items(type: 'integer'),
+            example: [1, 2, 3]
+        ),
+        new OA\Property(
+            property: 'allowed_view_types',
+            type: 'array',
+            description: 'Array of SummitBadgeViewType IDs, use expand=allowed_view_types for full details',
+            items: new OA\Items(type: 'integer'),
+            example: [1, 2, 3]
+        ),
+    ])
+]
+class SummitBadgeTypeSchema
+{
+}