fix(specs): Add context to hitsPerPage (#3969)

Co-authored-by: Gary Conroy <[email protected]>
Co-authored-by: Pierre Millot <[email protected]>

specs/common/parameters.yml

@@ -130,7 +130,15 @@ hitsPerPage:
   default: 20
   minimum: 1
   maximum: 1000
-  description: Maximum number of hits per page.
+  description: |
+    Maximum number of hits per page.
+
+    Algolia uses `page` and `hitsPerPage` to control how search results are displayed ([paginated](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/)).
+
+    - `hitsPerPage`: sets the number of search results (_hits_) displayed per page.
+    - `page`: specifies the page number of the search results you want to retrieve. Page numbering starts at 0, so the first page is `page=0`, the second is `page=1`, and so on.
+
+    For example, to display 10 results per page starting from the third page, set `hitsPerPage` to 10 and `page` to 2.
 
 query:
   type: string
@@ -140,7 +148,15 @@ query:
 page:
   type: integer
   minimum: 0
-  description: Requested page of the API response.
+  description: |
+    Requested page of the API response.
+
+    Algolia uses `page` and `hitsPerPage` to control how search results are displayed ([paginated](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/)).
+
+    - `hitsPerPage`: sets the number of search results (_hits_) displayed per page.
+    - `page`: specifies the page number of the search results you want to retrieve. Page numbering starts at 0, so the first page is `page=0`, the second is `page=1`, and so on.
+
+    For example, to display 10 results per page starting from the third page, set `hitsPerPage` to 10 and `page` to 2.
 
 count:
   description: Number of occurrences.