Feat | Add OpenAPI documentation for OAuth2UserRegistrationRequestApiController

[matiasperrone-exo]

Tasks:

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

Endpoints:

Method	Endpoint	Method Name
GET, HEAD	api/v1/users	getAll
OPTIONS, POST	api/v1/users	create
PUT	api/v1/users/info	userInfo

Summary by CodeRabbit

• Documentation
  • Added comprehensive OpenAPI/Swagger documentation for user registration endpoints, including request schemas, response schemas, and OAuth2 security configuration for better API integration guidance.

[martinquiroga-exo]

LGTM

[caseylocker]

LGTM

[matiasperrone-exo]

Rebased.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request adds comprehensive OpenAPI/Swagger documentation to the OAuth2 user registration API endpoints. It introduces schema classes for request payloads, response models, and security definitions, along with OpenAPI annotations to an existing controller, without altering business logic or control flow.

Changes

Cohort / File(s)	Summary
Controller API Documentation app/Http/Controllers/Api/OAuth2/OAuth2UserRegistrationRequestApiController.php	Adds OpenAPI annotations for three endpoints (GET, POST, PUT) including operation details, security requirements, parameters, request bodies, and response definitions.
Response & Model Schemas app/Swagger/Models/UserRegistrationRequestSchema.php, app/Swagger/OAuth2UserRegistrationRequestApiControllerSchemas.php	Defines OpenAPI schemas for user registration request models and paginated response structures with properties like email, name fields, country, and password link.
Request Body Schemas app/Swagger/Requests/CreateUserRegistrationRequestRequestSchema.php, app/Swagger/Requests/UpdateUserRegistrationRequestRequestSchema.php, app/Swagger/Requests/UserRegistrationRequestFieldsSchema.php	Introduces reusable request schemas for create and update operations, with shared field definitions for name, company, and country fields.
OAuth2 Security Scheme app/Swagger/Security/OAuth2UserRegistrationRequestApiControllerSecurityScheme.php	Defines OAuth2 authorization code flow security scheme with registration scope.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Hops with joy through specs so fine,
Documentation now shines divine,
Schemas neat in every place,
API docs with swagger grace!
🌟✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding OpenAPI documentation for a specific controller. It directly matches the changeset which adds comprehensive OpenAPI annotations across multiple schema files and controller methods.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ 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---oauth2userregistrationrequestapicontroller

📝 Coding Plan

• Generate coding plan for human review comments

---

_{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-108/

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

[coderabbitai]

🧹 Nitpick comments (2)

app/Swagger/OAuth2UserRegistrationRequestApiControllerSchemas.php (1)

1-6: Consider adding the license header for consistency.

Similar to UserRegistrationRequestSchema.php, this file is missing the Apache 2.0 license header present in other schema files.

🤖 Prompt for AI Agents

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

In `@app/Swagger/OAuth2UserRegistrationRequestApiControllerSchemas.php` around
lines 1 - 6, Add the standard Apache 2.0 license header to the top of this file
(the same header used in UserRegistrationRequestSchema.php and other schema
files) so the namespace declaration (namespace App\Swagger\schemas) and the use
statement (use OpenApi\Attributes as OA) are preceded by the license block;
ensure the header text exactly matches the project's existing Apache 2.0 header
for consistency.

app/Swagger/Models/UserRegistrationRequestSchema.php (1)

1-6: Consider adding the license header for consistency.

Other schema files in this PR include the Apache 2.0 license header. This file is missing it, which creates inconsistency across the codebase.

📝 Suggested fix

 <?php

 namespace App\Swagger\schemas;
+/**
+ * Copyright 2025 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/

 use OpenApi\Attributes as OA;

🤖 Prompt for AI Agents

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

In `@app/Swagger/Models/UserRegistrationRequestSchema.php` around lines 1 - 6, Add
the standard Apache 2.0 license header to the top of this file to match other
schema files; open the UserRegistrationRequestSchema.php file (namespace
App\Swagger\schemas) and insert the same multi-line Apache 2.0 comment block
used in other Swagger schema files before the opening <?php so the file header
is consistent with the rest of the PR.

🤖 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/Swagger/Models/UserRegistrationRequestSchema.php`:
- Around line 1-6: Add the standard Apache 2.0 license header to the top of this
file to match other schema files; open the UserRegistrationRequestSchema.php
file (namespace App\Swagger\schemas) and insert the same multi-line Apache 2.0
comment block used in other Swagger schema files before the opening <?php so the
file header is consistent with the rest of the PR.

In `@app/Swagger/OAuth2UserRegistrationRequestApiControllerSchemas.php`:
- Around line 1-6: Add the standard Apache 2.0 license header to the top of this
file (the same header used in UserRegistrationRequestSchema.php and other schema
files) so the namespace declaration (namespace App\Swagger\schemas) and the use
statement (use OpenApi\Attributes as OA) are preceded by the license block;
ensure the header text exactly matches the project's existing Apache 2.0 header
for consistency.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5844c027-aab7-4fef-97a9-adba2e69d618

📥 Commits

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

📒 Files selected for processing (7)

• app/Http/Controllers/Api/OAuth2/OAuth2UserRegistrationRequestApiController.php
• app/Swagger/Models/UserRegistrationRequestSchema.php
• app/Swagger/OAuth2UserRegistrationRequestApiControllerSchemas.php
• app/Swagger/Requests/CreateUserRegistrationRequestRequestSchema.php
• app/Swagger/Requests/UpdateUserRegistrationRequestRequestSchema.php
• app/Swagger/Requests/UserRegistrationRequestFieldsSchema.php
• app/Swagger/Security/OAuth2UserRegistrationRequestApiControllerSecurityScheme.php