Feat | Add OpenAPI documentation for OAuth2GroupApiController

[matiasperrone-exo]

Task:

Ref: https://app.clickup.com/t/86b8e6jrj

Endpoints:

Method	Endpoint	Method Name
GET,HEAD	api/v1/groups	getAll

Summary by CodeRabbit

• Documentation
  • Enhanced API documentation and specifications for the Groups API endpoints, including detailed endpoint schemas, parameters, and security requirements.

[martinquiroga-exo]

LGTM

@matiasperrone-exo please add the clickup card link to this PR.

[caseylocker]

1. Move #[OA\Get] from the class to getAllSerializerType() — Follow the pattern in OAuth2UserApiController where the annotation sits on getAllSerializerType(), not on the class declaration.
2. Use the existing user_oauth2 security scheme instead of creating OAuth2GroupsSecurity — user_oauth2 already covers Groups. Add IGroupScopes::ReadAll and IGroupScopes::Write to the scopes in
   app/Swagger/Security/UsersOAuth2Schema.php and reference user_oauth2 in the endpoint annotation. Remove OAuth2GroupApiControllerSecuritySchema.php.
3. Document the lack of route middleware — GET /api/v1/groups has no middleware in routes/api.php. The description field should note this (e.g., "No route-level middleware enforcement; requires valid OAuth2 bearer
   token only.").

[matiasperrone-exo]

Bullets 1 and 3 were incorporated:

1. Move #[OA\Get] from the class to getAllSerializerType() — Follow the pattern in OAuth2UserApiController where the annotation sits on getAllSerializerType(), not on the class declaration.

2. Document the lack of route middleware — GET /api/v1/groups has no middleware in routes/api.php. The description field should note this (e.g., "No route-level middleware enforcement; requires valid OAuth2 bearer
   token only.").

I have some questions regarding your comment (2nd bullet):

2. Use the existing user_oauth2 security scheme instead of creating OAuth2GroupsSecurity — user_oauth2 already covers Groups. Add IGroupScopes::ReadAll and IGroupScopes::Write to the scopes in
   app/Swagger/Security/UsersOAuth2Schema.php and reference user_oauth2 in the endpoint annotation. Remove OAuth2GroupApiControllerSecuritySchema.php.

This PR does not have UsersOAuth2Schema present, if I disregard that issue, are you sure you want to use the scopes from Users into Groups?

Taking into account that one comes from App\libs\OAuth2\IUserScopes and the this one (OAuth2GroupsSecurity) from App\libs\OAuth2\IGroupScopes.

If you are sure I will make the change.

[caseylocker]

Bullets 1 and 3 were incorporated:

1. Move #[OA\Get] from the class to getAllSerializerType() — Follow the pattern in OAuth2UserApiController where the annotation sits on getAllSerializerType(), not on the class declaration.
2. Document the lack of route middleware — GET /api/v1/groups has no middleware in routes/api.php. The description field should note this (e.g., "No route-level middleware enforcement; requires valid OAuth2 bearer
   token only.").

I have some questions regarding your comment (2nd bullet):

2. Use the existing user_oauth2 security scheme instead of creating OAuth2GroupsSecurity — user_oauth2 already covers Groups. Add IGroupScopes::ReadAll and IGroupScopes::Write to the scopes in
   app/Swagger/Security/UsersOAuth2Schema.php and reference user_oauth2 in the endpoint annotation. Remove OAuth2GroupApiControllerSecuritySchema.php.

This PR does not have UsersOAuth2Schema present, if I disregard that issue, are you sure you want to use the scopes from Users into Groups?

Taking into account that one comes from App\libs\OAuth2\IUserScopes and the this one (OAuth2GroupsSecurity) from App\libs\OAuth2\IGroupScopes.

If you are sure I will make the change.

That's a valid callout. Keep #2 as is.

[caseylocker]

LGTM

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request adds OpenAPI documentation annotations to the OAuth2 Groups API endpoint, including new schema definitions for paginated group responses and security configurations. No changes to existing API logic or method signatures.

Changes

Cohort / File(s)	Summary
API Controller Documentation app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php	Adds OpenAPI annotations to the getAll endpoint, including path, parameters (page, per_page, filter, order), HTTP responses (200, 401, 403, 404, 412, 500), and required imports for IGroupScopes and OA.
Swagger Schema Definitions app/Swagger/OAuth2GroupApiControllerSchemas.php, app/Swagger/Models/GroupSchema.php	Introduces PaginatedGroupResponseSchema class composing PaginateDataSchemaResponse with a data array of Group items; minor formatting adjustment in GroupSchema.
Swagger Security Schema app/Swagger/Security/OAuth2GroupApiControllerSecuritySchema.php	Adds OAuth2GroupApiControllerSecuritySchema class defining OAuth2 securityScheme with authorizationCode flow and group-related scopes (ReadAll, Write).

Poem

🐰 Our schemas now gleam with OpenAPI light,
Documentation blooms where the security's tight,
Groups march through endpoints, all properly bound,
With paginated responses and safe passage found! ✨

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding OpenAPI documentation for the OAuth2GroupApiController, which aligns with the changeset's additions of OA annotations and schema classes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/openapi----api-v1---oauth2groupapicontroller

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[matiasperrone-exo]

Rebased

[github-actions]

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-109/

This page is automatically updated on each push to this PR.

[coderabbitai]

🧹 Nitpick comments (1)

app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php (1)

49-51: Consider documenting the HEAD endpoint.

The PR objectives mention both GET and HEAD endpoints are mapped to getAll. While HEAD behavior typically mirrors GET (returning only headers), you may want to add an OA\Head annotation for completeness if the API explicitly supports HEAD requests.

📝 Optional: Add HEAD annotation

#[OA\Head(
    path: '/api/v1/groups',
    operationId: 'headGroups',
    summary: 'Check groups endpoint',
    description: 'Returns headers only for the groups endpoint.',
    security: [['OAuth2GroupsSecurity' => [IGroupScopes::ReadAll]]],
    tags: ['Groups'],
    responses: [
        new OA\Response(response: Response::HTTP_OK, description: 'Endpoint available'),
        new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: 'Unauthorized'),
    ]
)]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php` around lines 49
- 51, Add an OA\Head annotation for the '/api/v1/groups' endpoint to document
the HEAD method (mapped to the existing controller method getAll) so tooling
shows HEAD support; include operationId 'headGroups', a brief
summary/description, the same security entry as GET (IGroupScopes::ReadAll), the
'Groups' tag, and minimal responses (HTTP_OK and HTTP_UNAUTHORIZED) to mirror
GET's contract.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php`:
- Around line 49-51: Add an OA\Head annotation for the '/api/v1/groups' endpoint
to document the HEAD method (mapped to the existing controller method getAll) so
tooling shows HEAD support; include operationId 'headGroups', a brief
summary/description, the same security entry as GET (IGroupScopes::ReadAll), the
'Groups' tag, and minimal responses (HTTP_OK and HTTP_UNAUTHORIZED) to mirror
GET's contract.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4a104c78-dbf9-4f6d-850f-51c87c875d37

📥 Commits

Reviewing files that changed from the base of the PR and between 6d23f7f and 4693c58.

📒 Files selected for processing (4)

• app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php
• app/Swagger/Models/GroupSchema.php
• app/Swagger/OAuth2GroupApiControllerSchemas.php
• app/Swagger/Security/OAuth2GroupApiControllerSecuritySchema.php