docs: update docs about pages in search (#9887)

docs/api/ref/api.yml

@@ -280,6 +280,8 @@ paths:
         - $ref: './schemas/tags_parameters.yaml#/properties/tag_name_with_language_code'
         - $ref: '#/components/parameters/fields'
         - $ref: '#/components/parameters/sort_by'
+        - $ref: '#/components/parameters/page'
+        - $ref: '#/components/parameters/page_size'
     parameters: []
   /cgi/suggest.pl:
     get:
@@ -404,6 +406,22 @@ components:
       in: query
       name: angle
       required: true
+    page:
+      schema:
+        type: int
+        example: 24
+      in: query
+      name: page
+      description: |
+        The page number you request to view (eg. in search results spanning multiple pages)
+    page_size:
+      schema:
+        type: int
+        example: 24
+      in: query
+      name: page_size
+      description: |
+        The number of elements should be sent per page
     sort_by:
       schema:
         type: string

docs/api/ref/responses/search_for_products.yaml

@@ -8,17 +8,24 @@ properties:
   page:
     type: integer
     description: |
-      Page number of returned results
+      Page number of returned results.
+
+      You can get a different page, by using the `page` query parameter.
     example: 1
   page_count:
     type: integer
     description: |
-      Total number of pages
+      Number of products in this page.
+
+      This will differ from page_size only on the last page.
     example: 24
   page_size:
     type: integer
     description: |
-      Number of products per pages
+      Requested number of products per pages
+
+      To get the number of pages, divide count by page_size
+      (eg. `Math.floor( count / page_size) + 1 `)
     example: 24
   products:
     type: array