Feature | Extend Swagger Coverage for controller OAuth2UserStoriesApiController

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

@@ -1,4 +1,7 @@
-<?php namespace App\Http\Controllers;
+<?php
+
+namespace App\Http\Controllers;
+
 /**
  * Copyright 2024 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,9 +16,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 +46,74 @@ public function __construct
         $this->repository = $repository;
     }
 
+    // OpenAPI Documentation
+
+    #[OA\Get(
+        path: '/api/public/v1/user-stories',
+        operationId: 'getAllUserStories',
+        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 (Public)'],
+        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 +151,4 @@ protected function getEntitySerializerType(): string
         return !is_null($currentUser) ? SerializerRegistry::SerializerType_Private :
             SerializerRegistry::SerializerType_Public;
     }
-}
+}

app/Swagger/Models/ContinentSchema.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'Continent',
+    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', example: 'Example Organization'),
+
+    ])
+]
+class ContinentSchema
+{
+}

app/Swagger/Models/FileSchema.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'File',
+    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', example: 'example.png'),
+        new OA\Property(property: 'title', type: 'string', example: 'Awesome Picture'),
+        new OA\Property(property: 'url', type: 'string', example: 'https://example.com/files/example.png'),
+    ])
+]
+class FileSchema
+{
+}

app/Swagger/Models/OrganizationSchema.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'Organization',
+    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', example: 'Example Organization'),
+
+    ])
+]
+class OrganizationSchema
+{
+}

app/Swagger/Models/UserStoriesIndustrySchema.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'UserStoriesIndustry',
+    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', example: 'Example Organization'),
+        new OA\Property(property: 'active', type: 'boolean', example: true),
+
+    ])
+]
+class UserStoriesIndustrySchema
+{
+}

app/Swagger/Models/UserStorySchema.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+
+#[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_id', type: 'integer', example: 14),
+        new OA\Property(property: 'industry_id', type: 'integer', example: 14),
+        new OA\Property(property: 'location_id', type: 'integer', example: 14),
+        new OA\Property(property: 'image_id', type: 'integer', example: 14),
+        new OA\Property(property: 'organization', ref: '#/components/schemas/Organization', description: 'Organization object, only available if expanded via ?expand=organization'),
+        new OA\Property(property: 'industry', ref: '#/components/schemas/UserStoriesIndustry', description: 'UserStoriesIndustry object, only available if expanded via ?expand=industry'),
+        new OA\Property(property: 'location', ref: '#/components/schemas/Continent', description: 'Continent object, only available if expanded via ?expand=location'),
+        new OA\Property(property: 'image', ref: '#/components/schemas/File', description: 'File object, only available if expanded via ?expand=image'),
+        new OA\Property(
+            property: 'tags',
+            type: 'array',
+            description: 'Array of tag IDs, available only if included in ?relations=tags, use expand=tags for full objects instead of IDs',
+            items: new OA\Items(type: 'integer'),
+            example: [1, 2, 3]
+        ),
+    ]
+)]
+class UserStorySchema {}

app/Swagger/schemas.php

@@ -417,3 +417,23 @@ class ChunkedFileUploadCompleteResponseSchema {}
 )]
 class ChunkedFileUploadRequestSchema {}
 
+// User Stories
+
+
+#[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 {}