Feat | API OAuth2UserApiController routes v1

[matiasperrone-exo]

Task:

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

Endpoints:

Method	Endpoint	Method Name
GET,HEAD	api/v1/users	getAll
POST	api/v1/users	create
GET,HEAD	api/v1/users/info	userInfo
POST	api/v1/users/info	userInfo
GET,HEAD	api/v1/users/me	me
OPTIONS,PUT	api/v1/users/me	updateMe
OPTIONS,PUT	api/v1/users/me/pic	updateMyPic
GET,HEAD	api/v1/users/{id}	get
PUT	api/v1/users/{id}	update
PUT	api/v1/users/{id}/groups	updateUserGroups

Summary by CodeRabbit

• New Features

  • Added comprehensive user-management API metadata (list/search, current user, create/update, profile picture, UserInfo, group updates, v2 user view).

• Documentation

  • Ship extensive OpenAPI schemas for user request/response payloads, paginated responses, and expanded OAuth2 scopes (profile/email/address).

• Style

  • Minor formatting and structural cleanups; no runtime behavior or public API signatures changed.

[martinquiroga-exo]

LGTM

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

[caseylocker]

LGTM

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e245f161-968d-48d2-b98c-adb98fa9a988

📥 Commits

Reviewing files that changed from the base of the PR and between b545fb6 and 41ffab9.

📒 Files selected for processing (9)

• app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
• app/Swagger/Models/UserInfoResponseSchema.php
• app/Swagger/OAuth2UserApiControllerSchemas.php
• app/Swagger/Requests/CreateUserRequestSchema.php
• app/Swagger/Requests/UpdateUserGroupsRequestSchema.php
• app/Swagger/Requests/UpdateUserPicRequestSchema.php
• app/Swagger/Requests/UpdateUserRequestSchema.php
• app/Swagger/Requests/UserFieldsSchema.php
• app/Swagger/Security/UsersOAuth2Schema.php

✅ Files skipped from review due to trivial changes (2)

• app/Swagger/Requests/UpdateUserGroupsRequestSchema.php
• app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php

🚧 Files skipped from review as they are similar to previous changes (7)

• app/Swagger/Requests/CreateUserRequestSchema.php
• app/Swagger/Requests/UpdateUserRequestSchema.php
• app/Swagger/Security/UsersOAuth2Schema.php
• app/Swagger/OAuth2UserApiControllerSchemas.php
• app/Swagger/Requests/UpdateUserPicRequestSchema.php
• app/Swagger/Requests/UserFieldsSchema.php
• app/Swagger/Models/UserInfoResponseSchema.php

---

📝 Walkthrough

Walkthrough

Adds comprehensive OpenAPI attributes to the OAuth2 users controller and introduces multiple Swagger/OpenAPI schema classes (UserFields, Create/Update requests, UpdatePic/UpdateGroups, UserInfo address/response, PaginatedUserResponse) and updates the OAuth2 security scopes/schema.

Changes

Users API + Schemas

Layer / File(s)	Summary
UserFields schema app/Swagger/Requests/UserFieldsSchema.php	Adds UserFields OpenAPI schema enumerating all user properties, types, nullable flags, examples, and constraints.
Request schemas (create/update/pic/groups) app/Swagger/Requests/CreateUserRequestSchema.php, app/Swagger/Requests/UpdateUserRequestSchema.php, app/Swagger/Requests/UpdateUserPicRequestSchema.php, app/Swagger/Requests/UpdateUserGroupsRequestSchema.php	Adds CreateUserRequest, UpdateUserRequest (composes UserFields), UpdateUserPicRequest (binary file), and UpdateUserGroupsRequest (groups integer array).
UserInfo / Response Schemas app/Swagger/Models/UserInfoResponseSchema.php	Adds UserInfoAddressClaim and UserInfoResponse schemas modeling OIDC UserInfo claims (profile, email, groups, address).
Paginated user response app/Swagger/OAuth2UserApiControllerSchemas.php	Adds PaginatedUserResponse schema composed from pagination metadata and an array of User items.
OAuth2 security schema app/Swagger/Security/UsersOAuth2Schema.php	Renames security schema to UsersOAuth2Schema, expands scopes (Profile, Email, Address), and updates scope descriptions.
Controller / Endpoints app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php	Attaches OpenAPI attributes to endpoints: GET /api/v1/users, GET /api/v1/users/me, POST /api/v1/users, PUT /api/v1/users/me, PUT /api/v1/users/{id}, PUT /api/v1/users/me/pic, `GET

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• OpenStackweb/openstackid#119: Also touches Swagger/OpenAPI annotations for the users controller and may overlap on controller OpenAPI docs.

Poem

🐇 I padded through specs by moonlit beams,

Added claims and pictures, and tidy schemas it seems,
Scopes stretched wide, endpoints neatly penned,
Docs now humbly ready, from rabbit to friend.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main purpose of the changeset—adding OpenAPI documentation and routes for OAuth2UserApiController v1 endpoints.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

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

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 PHPStan (2.1.54)

Composer install failed: this project depends on private packages that require authentication (e.g. GitLab/GitHub, Laravel Nova, etc.).
CodeRabbit tooling environment cannot access private registries.
If your project requires private packages, disable the PHPStan tool in your coderabbit settings.

Instead, run PHPStan in a CI/CD pipeline where you can use custom packages — our pipeline remediation tool can use the PHPStan output from your CI/CD pipeline.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

📘 OpenAPI / Swagger preview

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

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

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php`:
- Around line 499-504: The OpenAPI response for the update operation in
OAuth2UserApiController currently uses HttpResponse::HTTP_CREATED (201); change
it to HttpResponse::HTTP_OK (200) so the OA\Response for the update (the block
creating new OA\Response in OAuth2UserApiController, around the
profile-picture/update endpoint) correctly reflects an update operation
returning 200 instead of 201.
- Around line 801-805: The OpenAPI annotation in OAuth2UserApiController
currently documents an update operation with response:
HttpResponse::HTTP_CREATED (201); change that OA\Response to use
HttpResponse::HTTP_OK (200) or HttpResponse::HTTP_NO_CONTENT (204) instead and
update the controller method that performs the user group assignment (the method
containing this OA\Response) so the actual HTTP response status it returns
matches the new code.
- Around line 397-402: The OpenAPI annotation in OAuth2UserApiController is
incorrectly using HttpResponse::HTTP_CREATED for a PUT update response; update
the OA\Response entry in the controller's update annotation to use
HttpResponse::HTTP_OK (200) so the documented status matches the update
semantics and returned User payload in the OA\JsonContent.
- Around line 450-455: The OpenAPI response annotation in
OAuth2UserApiController uses HttpResponse::HTTP_CREATED for an update endpoint;
change the response status to HttpResponse::HTTP_OK (200) to match an update
operation. Locate the OA\Response entry in the controller annotation (the block
that currently has response: HttpResponse::HTTP_CREATED and description
'Updated') and replace HttpResponse::HTTP_CREATED with HttpResponse::HTTP_OK
and, if desired, update the description to 'OK' or keep 'Updated' for clarity.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d9a428ab-13a3-4653-a1b3-9b59842b0f6b

📥 Commits

Reviewing files that changed from the base of the PR and between 446696c and 1a0c2b0.

📒 Files selected for processing (9)

• app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
• app/Swagger/Models/UserInfoResponseSchema.php
• app/Swagger/OAuth2UserApiControllerSchemas.php
• app/Swagger/Requests/CreateUserRequestSchema.php
• app/Swagger/Requests/UpdateUserGroupsRequestSchema.php
• app/Swagger/Requests/UpdateUserPicRequestSchema.php
• app/Swagger/Requests/UpdateUserRequestSchema.php
• app/Swagger/Requests/UserFieldsSchema.php
• app/Swagger/Security/UsersOAuth2Schema.php

[smarcet]

@matiasperrone-exo please review comments and rebase with main to get the proper preview for the swagger doc many thanks

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@app/Swagger/Security/UsersOAuth2Schema.php`:
- Line 3: The namespace declaration in UsersOAuth2Schema.php is incorrect
(currently App\Swagger\schemas) and breaks PSR-4 autoloading; update the
namespace to match the file path (use App\Swagger\Security) so the class
UsersOAuth2Schema is declared under the App\Swagger\Security namespace, then run
a quick Composer dump-autoload to verify resolution.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d9f0529e-eb78-4a4f-87f4-70c27e0a825a

📥 Commits

Reviewing files that changed from the base of the PR and between 1a0c2b0 and 174fd81.

📒 Files selected for processing (3)

• app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
• app/Swagger/OAuth2UserApiControllerSchemas.php
• app/Swagger/Security/UsersOAuth2Schema.php

🚧 Files skipped from review as they are similar to previous changes (1)

• app/Swagger/OAuth2UserApiControllerSchemas.php

[github-actions]

📘 OpenAPI / Swagger preview

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

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

[matiasperrone-exo]

@smarcet the branch was rebased

[github-actions]

📘 OpenAPI / Swagger preview

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

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

[matiasperrone-exo]

@smarcet please review again thanks!

[smarcet]

@matiasperrone-exo please review comments

[github-actions]

📘 OpenAPI / Swagger preview

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

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