add parameters

README.md

@@ -408,9 +408,36 @@ Output:
 
 NB: You may sort on multiple fields by using multiple "order" parameters. You can not order on "joined" columns.
 
+### Limit size
+
+The "size" parameter limits the number of returned records. This can be used for top N lists together with the "order" parameter (use descending order).
+
+```
+GET /records/categories?order=id&size=2
+```
+
+Output:
+
+```
+    {
+        "records":[
+            {
+                "id": 1
+                "name": "Internet"
+            },
+            {
+                "id": 3
+                "name": "Web development"
+            }
+        ]
+    }
+```
+
+NB: If you also want to know to the total number of records you may want to use the "page" parameter.
+
 ### Pagination
 
-The "page" parameter holds the requested page. The default page size is 20, but can be adjusted (e.g. to 50):
+The "page" parameter holds the requested page. The default page size is 20, but can be adjusted (e.g. to 50).
 
 ```
 GET /records/categories?order=id&page=1

api.php

@@ -3768,11 +3768,22 @@ class OpenApiBuilder
             if (!$this->isOperationOnTableAllowed($operation, $tableName)) {
                 continue;
             }
+            $parameters = [];
             if (in_array($operation, ['list', 'create'])) {
                 $path = sprintf('/records/%s', $tableName);
+                if ($operation == 'list') {
+                    $parameters = ['filter', 'include', 'exclude', 'order', 'size', 'page', 'join'];
+                }
             } else {
                 $path = sprintf('/records/%s/{%s}', $tableName, $pkName);
-                $this->openapi->set("paths|$path|$method|parameters|0|\$ref", "#/components/parameters/pk");
+                if ($operation == 'read') {
+                    $parameters = ['pk', 'include', 'exclude', 'join'];
+                } else {
+                    $parameters = ['pk'];
+                }
+            }
+            foreach ($parameters as $p => $parameter) {
+                $this->openapi->set("paths|$path|$method|parameters|$p|\$ref", "#/components/parameters/$parameter");
             }
             if (in_array($operation, ['create', 'update', 'increment'])) {
                 $this->openapi->set("paths|$path|$method|requestBody|\$ref", "#/components/requestBodies/$operation-" . urlencode($tableName));
@@ -3893,6 +3904,54 @@ class OpenApiBuilder
         $this->openapi->set("components|parameters|pk|schema|type", "string");
         $this->openapi->set("components|parameters|pk|description", "primary key value");
         $this->openapi->set("components|parameters|pk|required", true);
+
+        $this->openapi->set("components|parameters|filter|name", "filter");
+        $this->openapi->set("components|parameters|filter|in", "query");
+        $this->openapi->set("components|parameters|filter|schema|type", "array");
+        $this->openapi->set("components|parameters|filter|schema|items|type", "string");
+        $this->openapi->set("components|parameters|filter|description", "Filters to be applied. Each filter consists of a column, an operator and a value (comma separated). Example: id,eq,1");
+        $this->openapi->set("components|parameters|filter|required", false);
+        $this->openapi->set("components|parameters|filter|explode", false);
+        
+        $this->openapi->set("components|parameters|include|name", "include");
+        $this->openapi->set("components|parameters|include|in", "query");
+        $this->openapi->set("components|parameters|include|schema|type", "string");
+        $this->openapi->set("components|parameters|include|description", "Columns you want to include in the output (comma separated). Example: posts.*,categories.name");
+        $this->openapi->set("components|parameters|include|required", false);
+        
+        $this->openapi->set("components|parameters|exclude|name", "exclude");
+        $this->openapi->set("components|parameters|exclude|in", "query");
+        $this->openapi->set("components|parameters|exclude|schema|type", "string");
+        $this->openapi->set("components|parameters|exclude|description", "Columns you want to exclude from the output (comma separated). Example: posts.content");
+        $this->openapi->set("components|parameters|exclude|required", false);
+        
+        $this->openapi->set("components|parameters|order|name", "order");
+        $this->openapi->set("components|parameters|order|in", "query");
+        $this->openapi->set("components|parameters|order|schema|type", "array");
+        $this->openapi->set("components|parameters|order|schema|items|type", "string");
+        $this->openapi->set("components|parameters|order|description", "Column you want to sort on and the sort direction (comma separated). Example: id,desc");
+        $this->openapi->set("components|parameters|order|required", false);
+        $this->openapi->set("components|parameters|order|explode", false);
+
+        $this->openapi->set("components|parameters|size|name", "size");
+        $this->openapi->set("components|parameters|size|in", "query");
+        $this->openapi->set("components|parameters|size|schema|type", "string");
+        $this->openapi->set("components|parameters|size|description", "Maximum number of results (for top lists). Example: 10");
+        $this->openapi->set("components|parameters|size|required", false);
+
+        $this->openapi->set("components|parameters|page|name", "page");
+        $this->openapi->set("components|parameters|page|in", "query");
+        $this->openapi->set("components|parameters|page|schema|type", "string");
+        $this->openapi->set("components|parameters|page|description", "Page number and page size (comma separated). Example: 1,10");
+        $this->openapi->set("components|parameters|page|required", false);
+
+        $this->openapi->set("components|parameters|join|name", "join");
+        $this->openapi->set("components|parameters|join|in", "query");
+        $this->openapi->set("components|parameters|join|schema|type", "array");
+        $this->openapi->set("components|parameters|join|schema|items|type", "string");
+        $this->openapi->set("components|parameters|join|description", "Paths (comma separated) to related entities that you want to include. Example: comments,users");
+        $this->openapi->set("components|parameters|join|required", false);
+        $this->openapi->set("components|parameters|join|explode", false);
     }
 
     private function setTag(int $index, String $tableName) /*: void*/

src/Tqdev/PhpCrudApi/OpenApi/OpenApiBuilder.php

@@ -115,11 +115,22 @@ class OpenApiBuilder
             if (!$this->isOperationOnTableAllowed($operation, $tableName)) {
                 continue;
             }
+            $parameters = [];
             if (in_array($operation, ['list', 'create'])) {
                 $path = sprintf('/records/%s', $tableName);
+                if ($operation == 'list') {
+                    $parameters = ['filter', 'include', 'exclude', 'order', 'size', 'page', 'join'];
+                }
             } else {
                 $path = sprintf('/records/%s/{%s}', $tableName, $pkName);
-                $this->openapi->set("paths|$path|$method|parameters|0|\$ref", "#/components/parameters/pk");
+                if ($operation == 'read') {
+                    $parameters = ['pk', 'include', 'exclude', 'join'];
+                } else {
+                    $parameters = ['pk'];
+                }
+            }
+            foreach ($parameters as $p => $parameter) {
+                $this->openapi->set("paths|$path|$method|parameters|$p|\$ref", "#/components/parameters/$parameter");
             }
             if (in_array($operation, ['create', 'update', 'increment'])) {
                 $this->openapi->set("paths|$path|$method|requestBody|\$ref", "#/components/requestBodies/$operation-" . urlencode($tableName));
@@ -240,6 +251,54 @@ class OpenApiBuilder
         $this->openapi->set("components|parameters|pk|schema|type", "string");
         $this->openapi->set("components|parameters|pk|description", "primary key value");
         $this->openapi->set("components|parameters|pk|required", true);
+
+        $this->openapi->set("components|parameters|filter|name", "filter");
+        $this->openapi->set("components|parameters|filter|in", "query");
+        $this->openapi->set("components|parameters|filter|schema|type", "array");
+        $this->openapi->set("components|parameters|filter|schema|items|type", "string");
+        $this->openapi->set("components|parameters|filter|description", "Filters to be applied. Each filter consists of a column, an operator and a value (comma separated). Example: id,eq,1");
+        $this->openapi->set("components|parameters|filter|required", false);
+        $this->openapi->set("components|parameters|filter|explode", false);
+        
+        $this->openapi->set("components|parameters|include|name", "include");
+        $this->openapi->set("components|parameters|include|in", "query");
+        $this->openapi->set("components|parameters|include|schema|type", "string");
+        $this->openapi->set("components|parameters|include|description", "Columns you want to include in the output (comma separated). Example: posts.*,categories.name");
+        $this->openapi->set("components|parameters|include|required", false);
+        
+        $this->openapi->set("components|parameters|exclude|name", "exclude");
+        $this->openapi->set("components|parameters|exclude|in", "query");
+        $this->openapi->set("components|parameters|exclude|schema|type", "string");
+        $this->openapi->set("components|parameters|exclude|description", "Columns you want to exclude from the output (comma separated). Example: posts.content");
+        $this->openapi->set("components|parameters|exclude|required", false);
+        
+        $this->openapi->set("components|parameters|order|name", "order");
+        $this->openapi->set("components|parameters|order|in", "query");
+        $this->openapi->set("components|parameters|order|schema|type", "array");
+        $this->openapi->set("components|parameters|order|schema|items|type", "string");
+        $this->openapi->set("components|parameters|order|description", "Column you want to sort on and the sort direction (comma separated). Example: id,desc");
+        $this->openapi->set("components|parameters|order|required", false);
+        $this->openapi->set("components|parameters|order|explode", false);
+
+        $this->openapi->set("components|parameters|size|name", "size");
+        $this->openapi->set("components|parameters|size|in", "query");
+        $this->openapi->set("components|parameters|size|schema|type", "string");
+        $this->openapi->set("components|parameters|size|description", "Maximum number of results (for top lists). Example: 10");
+        $this->openapi->set("components|parameters|size|required", false);
+
+        $this->openapi->set("components|parameters|page|name", "page");
+        $this->openapi->set("components|parameters|page|in", "query");
+        $this->openapi->set("components|parameters|page|schema|type", "string");
+        $this->openapi->set("components|parameters|page|description", "Page number and page size (comma separated). Example: 1,10");
+        $this->openapi->set("components|parameters|page|required", false);
+
+        $this->openapi->set("components|parameters|join|name", "join");
+        $this->openapi->set("components|parameters|join|in", "query");
+        $this->openapi->set("components|parameters|join|schema|type", "array");
+        $this->openapi->set("components|parameters|join|schema|items|type", "string");
+        $this->openapi->set("components|parameters|join|description", "Paths (comma separated) to related entities that you want to include. Example: comments,users");
+        $this->openapi->set("components|parameters|join|required", false);
+        $this->openapi->set("components|parameters|join|explode", false);
     }
 
     private function setTag(int $index, String $tableName) /*: void*/