feat: Add OpenAPI documentation to "getAllUserStories" method

- Add controller's response to OpenAPI schema

Author: matiasperrone-exo

app/Http/Controllers/Apis/Protected/Main/OAuth2UserStoriesApiController.php

@@ -13,9 +13,11 @@
  **/
 
 use App\Models\Foundation\Main\Repositories\IUserStoryRepository;
+use Illuminate\Http\Response;
 use models\oauth2\IResourceServerContext;
 use models\utils\IEntity;
 use ModelSerializers\SerializerRegistry;
+use OpenApi\Attributes as OA;
 
 /**
  * Class OAuth2UserStoriesApiController
@@ -41,6 +43,73 @@ public function __construct
         $this->repository = $repository;
     }
 
+    // OpenAPI Documentation
+
+    #[OA\Get(
+        path: '/api/public/v1/user-stories',
+        summary: 'Get all user stories',
+        description: 'Retrieves a paginated list of user stories showcasing real-world use cases and success stories from the OpenStack community. User stories highlight how organizations use OpenStack in production. This is a public endpoint that can return different data based on authentication (more details for authenticated users).',
+        tags: ['User Stories'],
+        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: field<op>value. Available field: name (=@, ==, @@). Operators: == (equals), =@ (starts with), @@ (contains)',
+                style: 'form',
+                explode: true,
+                schema: new OA\Schema(
+                    type: 'array',
+                    items: new OA\Items(type: 'string', example: 'name@@cloud')
+                )
+            ),
+            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')
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                in: 'query',
+                required: false,
+                description: 'Expand relationships. Available: organization, industry, location, image, tags',
+                schema: new OA\Schema(type: 'string', example: 'organization,tags')
+            ),
+            new OA\Parameter(
+                name: 'relations',
+                in: 'query',
+                required: false,
+                description: 'Relations to load. Available: tags',
+                schema: new OA\Schema(type: 'string', example: 'tags')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'User stories retrieved successfully',
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedUserStoriesResponse')
+            ),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
+
     /**
      * @return mixed
      */
@@ -78,4 +147,4 @@ protected function getEntitySerializerType(): string
         return !is_null($currentUser) ? SerializerRegistry::SerializerType_Private :
             SerializerRegistry::SerializerType_Public;
     }
-}
+}

app/Swagger/schemas.php

@@ -376,3 +376,65 @@ class RSVPUpdateRequestSchema_{
     ]
 )]
 class RSVPAdminAddRequestSchema {}
+
+// Legal Documents
+
+#[OA\Schema(
+    schema: 'LegalDocument',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'title', type: 'string', example: 'Privacy Policy'),
+        new OA\Property(property: 'slug', type: 'string', example: 'privacy-policy'),
+        new OA\Property(property: 'content', type: 'string', example: 'This privacy policy describes how we handle your data...'),
+    ]
+)]
+class LegalDocumentSchema {}
+
+// User Stories
+
+#[OA\Schema(
+    schema: 'UserStory',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'created', type: 'integer', example: 1633024800, description: 'Unix timestamp when created'),
+        new OA\Property(property: 'last_edited', type: 'integer', example: 1633111200, description: 'Unix timestamp when last updated'),
+        new OA\Property(property: 'name', type: 'string', example: 'Large Scale Cloud Infrastructure'),
+        new OA\Property(property: 'description', type: 'string', example: 'Full description of how this organization uses OpenStack...'),
+        new OA\Property(property: 'short_description', type: 'string', example: 'Brief overview of the use case'),
+        new OA\Property(property: 'link', type: 'string', nullable: true, example: 'https://example.com/case-study'),
+        new OA\Property(property: 'active', type: 'boolean', example: true),
+        new OA\Property(property: 'is_million_core_club', type: 'boolean', example: false, description: 'Whether this is a million core club member'),
+        new OA\Property(property: 'organization', type: 'Organization'),
+        new OA\Property(property: 'industry', type: 'Industry'),
+        new OA\Property(property: 'location', type: 'Location'),
+        new OA\Property(property: 'image', type: 'Image'),
+        new OA\Property(
+            property: 'tags',
+            type: 'array',
+            description: 'Array of tag IDs (use expand=tags for full details)',
+            items: new OA\Items(type: 'integer'),
+            example: [1, 2, 3]
+        ),
+    ]
+)]
+class UserStorySchema {}
+
+#[OA\Schema(
+    schema: 'PaginatedUserStoriesResponse',
+    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/UserStory')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedUserStoriesResponseSchema {}