chore: Add unique operationId attribute to OpenAPI documentation

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

Author: matiasperrone-exo

app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php

@@ -55,6 +55,7 @@ final class OAuth2UserApiController extends OAuth2ProtectedController
     #[OA\Get(
         path: '/api/v1/users',
         summary: 'Get all users',
+        operationId: 'getUsers',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -211,6 +212,7 @@ public function __construct
     #[OA\Get(
         path: '/api/v1/users/me',
         summary: 'Get current user basic info',
+        operationId: 'getCurrentUser',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -328,12 +330,18 @@ private function _update($id){
     #[OA\Post(
         path: '/api/v1/users',
         summary: 'Create a new user',
+        operationId: 'createUser',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
                 IUserScopes::Write,
             ]],
         ],
+        requestBody: new OA\RequestBody(
+            description: 'User data',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/CreateUserRequest')
+        ),
         responses: [
             new OA\Response(
                 response: HttpResponse::HTTP_CREATED,
@@ -365,12 +373,18 @@ public function create(){
     #[OA\Put(
         path: '/api/v1/users/me',
         summary: 'Update current user',
+        operationId: 'updateCurrentUser',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
                 IUserScopes::MeWrite,
             ]],
         ],
+        requestBody: new OA\RequestBody(
+            description: 'User data to update',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserRequest')
+        ),
         responses: [
             new OA\Response(
                 response: HttpResponse::HTTP_CREATED,
@@ -402,6 +416,7 @@ public function updateMe(){
     #[OA\Put(
         path: '/api/v1/users/{id}',
         summary: 'Update a user by ID',
+        operationId: 'updateUser',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -417,6 +432,11 @@ public function updateMe(){
                 schema: new OA\Schema(type: 'integer')
             ),
         ],
+        requestBody: new OA\RequestBody(
+            description: 'User data to update',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserRequest')
+        ),
         responses: [
             new OA\Response(
                 response: HttpResponse::HTTP_CREATED,
@@ -448,6 +468,7 @@ public function update($id){
     #[OA\Put(
         path: '/api/v1/users/me/pic',
         summary: 'Update current user profile picture',
+        operationId: 'updateCurrentUserProfilePicture',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -511,6 +532,7 @@ public function updateMyPic(LaravelRequest $request){
     #[OA\Get(
         path: '/api/v1/users/info',
         summary: 'Get current user info (OpenID Connect UserInfo)',
+        operationId: 'getUserInfo',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -533,6 +555,7 @@ public function updateMyPic(LaravelRequest $request){
     #[OA\Post(
         path: '/api/v1/users/info',
         summary: 'Get current user info (OpenID Connect UserInfo)',
+        operationId: 'getUserInfoPost',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -591,6 +614,7 @@ public function userInfo()
     #[OA\Get(
         path: '/api/v1/users/{id}',
         summary: 'Get a user by ID',
+        operationId: 'getUserById',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -672,6 +696,7 @@ public function getV2($id)
     #[OA\Put(
         path: '/api/v1/users/{id}/groups',
         summary: 'Update user group assignments',
+        operationId: 'updateUserGroups',
         tags: ['Users'],
         security: [
             ['user_oauth2' => [
@@ -687,6 +712,11 @@ public function getV2($id)
                 schema: new OA\Schema(type: 'integer')
             ),
         ],
+        requestBody: new OA\RequestBody(
+            description: 'Group IDs to assign',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserGroupsRequest')
+        ),
         responses: [
             new OA\Response(
                 response: HttpResponse::HTTP_CREATED,

app/Swagger/Requests/CreateUserRequestSchema.php

@@ -0,0 +1,30 @@
+<?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;
+
+#[OA\Schema(
+    schema: 'CreateUserRequest',
+    title: 'Create User Request',
+    description: 'Request body for creating a new user. Only email is required, all other fields are optional.',
+    type: 'object',
+    required: ['email'],
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/UserFields')
+    ]
+)]
+class CreateUserRequestSchema
+{
+}

app/Swagger/Requests/UpdateUserGroupsRequestSchema.php

@@ -0,0 +1,36 @@
+<?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;
+
+#[OA\Schema(
+    schema: 'UpdateUserGroupsRequest',
+    title: 'Update User Groups Request',
+    description: 'Request body for updating user group assignments',
+    type: 'object',
+    required: ['groups'],
+    properties: [
+        new OA\Property(
+            property: 'groups',
+            type: 'array',
+            items: new OA\Items(type: 'integer'),
+            description: 'Array of group IDs to assign to the user',
+            example: [1, 2, 3]
+        )
+    ]
+)]
+class UpdateUserGroupsRequestSchema
+{
+}