Skip to content

Feat | Add OpenAPI documentation for OAuth2StreamChatSSOApiController #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
matiasperrone-exo wants to merge 1 commit into
base: main
Choose a base branch
from
+92 −0
Open

Feat | Add OpenAPI documentation for OAuth2StreamChatSSOApiController #110

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions app/Http/Controllers/Api/OAuth2/OAuth2StreamChatSSOApiController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,14 @@
* See the License for the specific language governing permissions and
* limitations under the License.
**/
use App\libs\OAuth2\IUserScopes;
use App\Services\Auth\IStreamChatSSOService;
use Illuminate\Support\Facades\Log;
use models\exceptions\EntityNotFoundException;
use models\exceptions\ValidationException;
use OAuth2\IResourceServerContext;
use OpenApi\Attributes as OA;
use Symfony\Component\HttpFoundation\Response as HttpResponse;
use Utils\Services\ILogService;
/**
* Class OAuth2StreamChatSSOApiController
Expand Down Expand Up @@ -44,6 +47,50 @@ public function __construct
* @param string $forum_slug
* @return \Illuminate\Http\JsonResponse|mixed
*/
#[OA\Get(
path: '/api/v1/sso/stream-chat/{forum_slug}/profile',
operationId: 'getStreamChatUserProfile',
summary: 'Get Stream Chat user profile for a forum',
description: 'Returns the Stream Chat user profile and authentication token for the given forum. Requires SSO scope.',
security: [['OAuth2StreamChatSSOSecurity' => [IUserScopes::SSO]]],
tags: ['Stream Chat SSO'],
parameters: [
new OA\Parameter(
name: 'forum_slug',
description: 'Forum slug',
in: 'path',
required: true,
schema: new OA\Schema(type: 'string')
),
],
responses: [
new OA\Response(
response: HttpResponse::HTTP_OK,
description: 'OK',
content: new OA\JsonContent(ref: '#/components/schemas/StreamChatUserProfile')
),
new OA\Response(
response: HttpResponse::HTTP_NOT_FOUND,
description: 'Not Found'
),
new OA\Response(
response: HttpResponse::HTTP_PRECONDITION_FAILED,
description: 'Validation Error'
),
new OA\Response(
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
description: 'Server Error'
),
new OA\Response(
response: HttpResponse::HTTP_UNAUTHORIZED,
description: 'Unauthorized - invalid or missing token'
),
new OA\Response(
response: HttpResponse::HTTP_FORBIDDEN,
description: 'Forbidden - insufficient scope'
),
]
Comment on lines +66 to +92
Copy link

@coderabbitai coderabbitai bot Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== Response helpers used by OAuth2StreamChatSSOApiController ==="
rg -n -C4 'class\s+OAuth2ProtectedController\b|function\s+(ok|error404|error412|error500)\s*\(' --glob '*.php'

echo
echo "=== Stream Chat SSO payload serialization ==="
rg -n -C4 'IStreamChatSSOService|class\s+.*StreamChat.*|function\s+getUserProfile\s*\(|function\s+serialize\s*\(' --glob '*.php'

Repository: OpenStackweb/openstackid

Length of output: 35631

🏁 Script executed:

sed -n '94,115p' app/Http/Controllers/Api/OAuth2/OAuth2StreamChatSSOApiController.php

Repository: OpenStackweb/openstackid

Length of output: 691

Add content specifications to 404 and 412 responses.

Line 97 returns the serialized profile directly via ok(), but lines 101 and 106 emit structured JSON through error412() and error404() respectively. The OpenAPI documentation currently omits content for the 404 and 412 responses, though they do emit JSON bodies:

  • 404 returns {"message": "..."} via error404()
  • 412 returns {"message": "Validation Failed", "errors": [...]} via error412()

Update the 404 and 412 response definitions to specify their actual JSON content schemas, or verify the 200 response schema correctly describes the flat profile object.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@app/Http/Controllers/Api/OAuth2/OAuth2StreamChatSSOApiController.php` around
lines 66 - 92, The OpenAPI responses for 404 and 412 in
OAuth2StreamChatSSOApiController.php are missing JSON content schemas while the
controller actually returns JSON via error404() and error412(); update the
OA\Response entries for HttpResponse::HTTP_NOT_FOUND and
HttpResponse::HTTP_PRECONDITION_FAILED to include a content: new
OA\JsonContent(...) that matches the real payload (e.g., a simple {"message":
"..."} schema for 404 and a {"message":"Validation Failed","errors":[...]}
validation-error schema for 412), or reference existing components like
StreamChatUserProfile for 200 and a shared ErrorResponse / ValidationError
schema if available, so the OpenAPI docs accurately reflect the returned JSON
bodies.

)]
public function getUserProfile(string $forum_slug){
try{
$profile = $this->service->getUserProfile($forum_slug);
Expand Down
22 changes: 22 additions & 0 deletions app/Swagger/Models/StreamChatUserProfileSchema.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<?php

namespace App\Swagger\schemas;

use OpenApi\Attributes as OA;

#[OA\Schema(
schema: 'StreamChatUserProfile',
type: 'object',
properties: [
new OA\Property(property: 'id', type: 'string', description: 'User ID'),
new OA\Property(property: 'name', type: 'string', description: 'Display name'),
new OA\Property(property: 'image', type: 'string', format: 'uri', description: 'Avatar URL'),
new OA\Property(property: 'token', type: 'string', description: 'Stream Chat JWT token'),
new OA\Property(property: 'api_key', type: 'string', description: 'Stream Chat API key'),
new OA\Property(property: 'local_role', type: 'string', description: 'User role in the forum'),
],
description: 'Stream Chat SSO user profile'
)]
class StreamChatUserProfileSchema
{
}
23 changes: 23 additions & 0 deletions app/Swagger/Security/OAuth2StreamChatSSOApiControllerSecuritySchema.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<?php

namespace App\Swagger\schemas;

use App\libs\OAuth2\IUserScopes;
use OpenApi\Attributes as OA;

#[OA\SecurityScheme(
securityScheme: 'OAuth2StreamChatSSOSecurity',
type: 'oauth2',
description: 'OAuth2 authentication for Stream Chat SSO endpoints',
flows: [
new OA\Flow(
flow: 'authorizationCode',
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
scopes: [IUserScopes::SSO => 'Single Sign-On access']
),
]
)]
class OAuth2StreamChatSSOApiControllerSecuritySchema
{
}
Loading