HLAPI Expand endpoint docs

* add rsql query param to spec
* add default descriptions for components
* add entity, profile and recursive params to spec
* add missing params and responses
* placeholder support for expanded path responses
* placeholders for path params
* add placeholders to route docs
* add global lang parameter

Author: cconard96

src/Api/HL/Controller/AbstractController.php

@@ -72,6 +72,38 @@ abstract class AbstractController
     public const CRUD_ACTION_RESTORE = 'restore';
     public const CRUD_ACTION_LIST = 'list';
 
+    protected const PARAMETER_RSQL_FILTER = [
+        'name' => 'filter',
+        'description' => 'RSQL query string',
+        'location' => 'query',
+        'schema' => [
+            'type' => Doc\Schema::TYPE_STRING,
+        ]
+    ];
+
+    protected const PARAMETER_START = [
+        'name' => 'start',
+        'description' => 'The first item to return',
+        'location' => 'query',
+        'schema' => [
+            'type' => Doc\Schema::TYPE_INTEGER,
+            'format' => Doc\Schema::FORMAT_INTEGER_INT64,
+            'minimum' => 0,
+            'default' => 0,
+        ]
+    ];
+
+    protected const PARAMETER_LIMIT = [
+        'name' => 'limit',
+        'description' => 'The maximum number of items to return',
+        'location' => 'query',
+        'schema' => [
+            'type' => Doc\Schema::TYPE_INTEGER,
+            'format' => Doc\Schema::FORMAT_INTEGER_INT64,
+            'minimum' => 0,
+        ]
+    ];
+
     /**
      * @return array<string, Doc\Schema>
      */

src/Api/HL/Controller/AdministrationController.php

@@ -330,6 +330,7 @@ public static function getRawKnownSchemas(): array
     #[Route(path: '/User', methods: ['GET'], middlewares: [ResultFormatterMiddleware::class])]
     #[Doc\Route(
         description: 'List or search users',
+        parameters: [self::PARAMETER_RSQL_FILTER, self::PARAMETER_START, self::PARAMETER_LIMIT],
         responses: [
             ['schema' => 'User[]']
         ]
@@ -342,6 +343,7 @@ public function searchUsers(Request $request): Response
     #[Route(path: '/Group', methods: ['GET'], middlewares: [ResultFormatterMiddleware::class])]
     #[Doc\Route(
         description: 'List or search groups',
+        parameters: [self::PARAMETER_RSQL_FILTER, self::PARAMETER_START, self::PARAMETER_LIMIT],
         responses: [
             ['schema' => 'Group[]']
         ]
@@ -354,6 +356,7 @@ public function searchGroups(Request $request): Response
     #[Route(path: '/Entity', methods: ['GET'], middlewares: [ResultFormatterMiddleware::class])]
     #[Doc\Route(
         description: 'List or search entities',
+        parameters: [self::PARAMETER_RSQL_FILTER, self::PARAMETER_START, self::PARAMETER_LIMIT],
         responses: [
             ['schema' => 'Entity[]']
         ]
@@ -366,6 +369,7 @@ public function searchEntities(Request $request): Response
     #[Route(path: '/Profile', methods: ['GET'], middlewares: [ResultFormatterMiddleware::class])]
     #[Doc\Route(
         description: 'List or search profiles',
+        parameters: [self::PARAMETER_RSQL_FILTER, self::PARAMETER_START, self::PARAMETER_LIMIT],
         responses: [
             ['schema' => 'Profile[]']
         ]
@@ -546,7 +550,6 @@ public function getMyPicture(Request $request): Response
         [
             'name' => '_',
             'location' => Doc\Parameter::LOCATION_BODY,
-            'type' => Doc\Schema::TYPE_OBJECT,
             'schema' => 'User',
         ]
     ])]
@@ -678,7 +681,6 @@ public function deleteUserByUsername(Request $request): Response
         [
             'name' => '_',
             'location' => Doc\Parameter::LOCATION_BODY,
-            'type' => Doc\Schema::TYPE_OBJECT,
             'schema' => 'Group',
         ]
     ])]
@@ -731,7 +733,6 @@ public function deleteGroupByID(Request $request): Response
         [
             'name' => '_',
             'location' => Doc\Parameter::LOCATION_BODY,
-            'type' => Doc\Schema::TYPE_OBJECT,
             'schema' => 'Entity',
         ]
     ])]
@@ -784,7 +785,6 @@ public function deleteEntityByID(Request $request): Response
         [
             'name' => '_',
             'location' => Doc\Parameter::LOCATION_BODY,
-            'type' => Doc\Schema::TYPE_OBJECT,
             'schema' => 'Profile',
         ]
     ])]