diff --git a/core/openapi.md b/core/openapi.md
index 4f4fd577b6c..6c1494d072e 100644
--- a/core/openapi.md
+++ b/core/openapi.md
@@ -900,6 +900,22 @@ To enable API Gateway compatibility on your OpenAPI docs, add `api_gateway=true`
 `http://www.example.com/docs.jsonopenapi?api_gateway=true`. The flag `--api-gateway` is also
 available through the command-line.
 
+The compatibility layer removes every query parameter whose name does not match
+`^[a-zA-Z0-9._$-]+$` from the generated specification. Bracketed filter parameters such as
+`order[title]` or `exists[author]` are dropped, not renamed. To keep a filter usable behind API
+Gateway, declare it with a [`QueryParameter`](filters.md#declaring-parameters) and a bracket-free
+key:
+
+```php
+use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\QueryParameter;
+
+#[GetCollection(parameters: [
+    'order_title' => new QueryParameter(filter: new SortFilter(), property: 'title'),
+])]
+```
+
 ## OAuth
 
 ### OAuth using Symfony