improve API endpoint names (#5502)

src/API/ActivityController.php

@@ -53,7 +53,7 @@ final class ActivityController extends BaseApiController
     }
 
     /**
-     * Fetch collection of activities
+     * Fetch activities
      */
     #[OA\Response(response: 200, description: 'Returns a collection of activities', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/ActivityCollection')))]
     #[Route(methods: ['GET'], path: '', name: 'get_activities')]
@@ -176,7 +176,7 @@ final class ActivityController extends BaseApiController
     }
 
     /**
-     * Update an existing activity
+     * Update activity
      */
     #[IsGranted('edit', 'activity')]
     #[OA\Patch(description: 'Update an existing activity, you can pass all or just a subset of all attributes', responses: [new OA\Response(response: 200, description: 'Returns the updated activity', content: new OA\JsonContent(ref: '#/components/schemas/ActivityEntity'))])]
@@ -212,10 +212,10 @@ final class ActivityController extends BaseApiController
     }
 
     /**
-     * Delete an existing activity
+     * Delete activity
      *
      * [DANGER] This will also delete ALL linked timesheets.
-     * Maybe use `PATCH` instead and mark it as inactive with `visible=false`?
+     * Do you want to use `PATCH` instead and mark it as inactive with `{visible: false}` instead?
      */
     #[IsGranted('delete', 'activity')]
     #[OA\Delete(responses: [new OA\Response(response: 204, description: 'Delete one activity')])]
@@ -262,7 +262,7 @@ final class ActivityController extends BaseApiController
     }
 
     /**
-     * Fetch all rates for one activity
+     * Fetch rates for activity
      */
     #[IsGranted('edit', 'activity')]
     #[OA\Response(response: 200, description: 'Returns a collection of activity rate entities', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/ActivityRate')))]
@@ -300,7 +300,7 @@ final class ActivityController extends BaseApiController
     }
 
     /**
-     * Add rate for one activity
+     * Add rate for activity
      */
     #[IsGranted('edit', 'activity')]
     #[OA\Post(responses: [new OA\Response(response: 200, description: 'Returns the new created rate', content: new OA\JsonContent(ref: '#/components/schemas/ActivityRate'))])]

src/API/CustomerController.php

@@ -52,7 +52,7 @@ final class CustomerController extends BaseApiController
     }
 
     /**
-     * Fetch collection of customers
+     * Fetch customers
      */
     #[OA\Response(response: 200, description: 'Returns a collection of customers', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/CustomerCollection')))]
     #[Route(methods: ['GET'], path: '', name: 'get_customers')]
@@ -151,7 +151,7 @@ final class CustomerController extends BaseApiController
     }
 
     /**
-     * Update an existing customer
+     * Update customer
      */
     #[IsGranted('edit', 'customer')]
     #[OA\Patch(description: 'Update an existing customer, you can pass all or just a subset of all attributes', responses: [new OA\Response(response: 200, description: 'Returns the updated customer', content: new OA\JsonContent(ref: '#/components/schemas/CustomerEntity'))])]
@@ -187,10 +187,10 @@ final class CustomerController extends BaseApiController
     }
 
     /**
-     * Delete an existing customer
+     * Delete customer
      *
      * [DANGER] This will also delete ALL linked projects, project activities and timesheets.
-     * Maybe use `PATCH` instead and mark it as inactive with `visible=false`?
+     * Do you want to use `PATCH` instead and mark it as inactive with `{visible: false}` instead?
      */
     #[IsGranted('delete', 'customer')]
     #[OA\Delete(responses: [new OA\Response(response: 204, description: 'Delete one customer')])]
@@ -237,7 +237,7 @@ final class CustomerController extends BaseApiController
     }
 
     /**
-     * Fetch all rates for one customer
+     * Fetch rates for customer
      */
     #[IsGranted('edit', 'customer')]
     #[OA\Response(response: 200, description: 'Returns a collection of customer rate entities', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/CustomerRate')))]
@@ -275,7 +275,7 @@ final class CustomerController extends BaseApiController
     }
 
     /**
-     * Add rate for one customer
+     * Add rate for customer
      */
     #[IsGranted('edit', 'customer')]
     #[OA\Post(responses: [new OA\Response(response: 200, description: 'Returns the new created rate', content: new OA\JsonContent(ref: '#/components/schemas/CustomerRate'))])]

src/API/InvoiceController.php

@@ -38,7 +38,7 @@ final class InvoiceController extends BaseApiController
     }
 
     /**
-     * Fetch collection of invoices
+     * Fetch invoices
      */
     #[IsGranted('view_invoice')]
     #[OA\Response(response: 200, description: 'Returns a collection of invoices', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/InvoiceCollection')))]

src/API/ProjectController.php

@@ -54,7 +54,7 @@ final class ProjectController extends BaseApiController
     }
 
     /**
-     * Fetch collection of projects
+     * Fetch projects
      */
     #[OA\Response(response: 200, description: 'Returns a collection of projects', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/ProjectCollection')))]
     #[Route(methods: ['GET'], path: '', name: 'get_projects')]
@@ -151,7 +151,7 @@ final class ProjectController extends BaseApiController
     }
 
     /**
-     * Returns one project
+     * Fetch project
      */
     #[OA\Response(response: 200, description: 'Returns one project entity', content: new OA\JsonContent(ref: '#/components/schemas/ProjectEntity'))]
     #[Route(methods: ['GET'], path: '/{id}', name: 'get_project', requirements: ['id' => '\d+'])]
@@ -203,7 +203,7 @@ final class ProjectController extends BaseApiController
     }
 
     /**
-     * Update an existing project
+     * Update project
      */
     #[IsGranted('edit', 'project')]
     #[OA\Patch(description: 'Update an existing project, you can pass all or just a subset of all attributes', responses: [new OA\Response(response: 200, description: 'Returns the updated project', content: new OA\JsonContent(ref: '#/components/schemas/ProjectEntity'))])]
@@ -241,10 +241,10 @@ final class ProjectController extends BaseApiController
     }
 
     /**
-     * Delete an existing project
+     * Delete project
      *
      * [DANGER] This will also delete ALL linked activities and timesheets.
-     * Maybe use `PATCH` instead and mark it as inactive with `visible=false`?
+     * Do you want to use `PATCH` instead and mark it as inactive with `{visible: false}` instead?
      */
     #[IsGranted('delete', 'project')]
     #[OA\Delete(responses: [new OA\Response(response: 204, description: 'Delete one project')])]
@@ -291,7 +291,7 @@ final class ProjectController extends BaseApiController
     }
 
     /**
-     * Fetch all rates for one project
+     * Fetch rates for project
      */
     #[IsGranted('edit', 'project')]
     #[OA\Response(response: 200, description: 'Returns a collection of project rate entities', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/ProjectRate')))]
@@ -329,7 +329,7 @@ final class ProjectController extends BaseApiController
     }
 
     /**
-     * Add rate for one project
+     * Add rate for project
      */
     #[IsGranted('edit', 'project')]
     #[OA\Post(responses: [new OA\Response(response: 200, description: 'Returns the new created rate', content: new OA\JsonContent(ref: '#/components/schemas/ProjectRate'))])]

src/API/TagController.php

@@ -59,7 +59,7 @@ final class TagController extends BaseApiController
     }
 
     /**
-     * Fetch collection of tags
+     * Fetch tags
      */
     #[OA\Response(response: 200, description: 'Find the collection of all matching tags', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/TagEntity')))]
     #[Route(path: '/find', name: 'get_tags_full', methods: ['GET'])]
@@ -113,7 +113,7 @@ final class TagController extends BaseApiController
     }
 
     /**
-     * Delete a tag
+     * Delete tag
      */
     #[IsGranted('delete_tag')]
     #[OA\Delete(responses: [new OA\Response(response: 204, description: 'HTTP code 204 for a successful delete')])]

src/API/TeamController.php

@@ -47,7 +47,7 @@ final class TeamController extends BaseApiController
     }
 
     /**
-     * Fetch collection of teams
+     * Fetch teams
      */
     #[IsGranted('view_team')]
     #[OA\Response(response: 200, description: 'Returns a collection of teams', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/TeamCollection')))]

src/API/TimesheetController.php

@@ -68,7 +68,7 @@ final class TimesheetController extends BaseApiController
     }
 
     /**
-     * Fetch collection of timesheets
+     * Fetch timesheets
      */
     #[IsGranted(new Expression("is_granted('view_own_timesheet') or is_granted('view_other_timesheet')"))]
     #[OA\Response(response: 200, description: 'Returns a collection of timesheets. The datetime fields are given in the users local time including the timezone offset (ISO-8601).', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/TimesheetCollection')))]
@@ -270,7 +270,7 @@ final class TimesheetController extends BaseApiController
     }
 
     /**
-     * Return timesheet
+     * Fetch timesheet
      */
     #[IsGranted('view', 'timesheet')]
     #[OA\Response(response: 200, description: 'Returns one timesheet. Be aware that the datetime fields are given in the users local time including the timezone offset via ISO 8601.', content: new OA\JsonContent(ref: '#/components/schemas/TimesheetEntity'))]
@@ -472,7 +472,9 @@ final class TimesheetController extends BaseApiController
     }
 
     /**
-     * Restart a timesheet for the current user
+     * Restart timesheet
+     *
+     * The restarted timesheet will be created for the current user
      */
     #[IsGranted('start', 'timesheet')]
     #[OA\Response(response: 200, description: 'Restart a timesheet for the same customer, project, activity combination. The current user will be the owner of the new record. Kimai tries to stop running records, which is expected to fail depending on the configured rules. Data will be copied from the original record if requested.', content: new OA\JsonContent(ref: '#/components/schemas/TimesheetEntity'))]
@@ -534,7 +536,7 @@ final class TimesheetController extends BaseApiController
     }
 
     /**
-     * Duplicate a timesheet
+     * Duplicate timesheet
      */
     #[IsGranted('duplicate', 'timesheet')]
     #[OA\Response(response: 200, description: 'Duplicates a timesheet, resetting the export state only.', content: new OA\JsonContent(ref: '#/components/schemas/TimesheetEntity'))]

src/API/UserController.php

@@ -47,7 +47,7 @@ final class UserController extends BaseApiController
     }
 
     /**
-     * Fetch collection of users
+     * Fetch users
      */
     #[IsGranted('view_user')]
     #[OA\Response(response: 200, description: 'Returns a collection of users. Required permission: view_user', content: new OA\JsonContent(type: 'array', items: new OA\Items(ref: '#/components/schemas/UserCollection')))]
@@ -97,7 +97,7 @@ final class UserController extends BaseApiController
     }
 
     /**
-     * Return one user entity
+     * Fetch user
      */
     #[IsGranted('view', 'profile')]
     #[OA\Response(response: 200, description: 'Return one user entity.', content: new OA\JsonContent(ref: '#/components/schemas/UserEntity'))]
@@ -116,7 +116,7 @@ final class UserController extends BaseApiController
     }
 
     /**
-     * Return the current user entity
+     * Fetch current user
      */
     #[OA\Response(response: 200, description: 'Return the current user entity.', content: new OA\JsonContent(ref: '#/components/schemas/UserEntity'))]
     #[Route(methods: ['GET'], path: '/me', name: 'me_user')]
@@ -199,7 +199,9 @@ final class UserController extends BaseApiController
     }
 
     /**
-     * Delete API token for the current user
+     * Delete API token
+     *
+     * This ONLY works if the given API token exists and belongs to the current user
      */
     #[OA\Delete(responses: [new OA\Response(response: 200, description: 'Success if the token could be deleted.')])]
     #[OA\Parameter(name: 'id', in: 'path', description: 'The API token ID to remove', required: true)]