feat(openapi): describe nextPage and previousPage as page paths

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.1.0 (2026-10-15)
+
+### Changed
+
+- `page.nextPage` and `page.previousPage` in list responses (`GET /menu`, `GET /orders`) are now the path of the adjacent page, relative to the server URL, for example `/menu?limit=10&after=G0EAAIyUqm8V`.
+  The path keeps the query parameters of the request.
+  Request it directly instead of passing the value as the `after` or `before` parameter.
+  The `after` and `before` parameters still accept a cursor, which is the value of that parameter in the path.
+
 ## 1.0.1 (2026-10-14)
 
 ### Changed

openapi/cafe.yaml

@@ -4,7 +4,7 @@ info:
   description: |
     Demo API for cafe operators (not customers) to manage menus, orders, and revenue.
     Create API credentials and try it yourself in a realistic OpenAPI workflow.
-  version: 1.0.1
+  version: 1.1.0
   contact:
     email: team@redocly.com
     url: https://redocly.com/contact-us/

openapi/components/parameters/After.yaml

@@ -1,6 +1,9 @@
 name: after
 in: query
 required: false
-description: Use the `nextPage` value as the `after` parameter to get the next page.
+description: |-
+  Cursor of the next page.
+  `page.nextPage` contains it as the `after` query parameter, so you can also request `page.nextPage` directly.
+  The cursor is opaque, and its internal structure is subject to change.
 schema:
   type: string

openapi/components/parameters/Before.yaml

@@ -1,7 +1,9 @@
 name: before
 in: query
 required: false
-description: |
-  Use the `previousPage` value as the `before` parameter to get the previous page.
+description: |-
+  Cursor of the previous page.
+  `page.previousPage` contains it as the `before` query parameter, so you can also request `page.previousPage` directly.
+  The cursor is opaque, and its internal structure is subject to change.
 schema:
   type: string

openapi/components/schemas/Page.yaml

@@ -4,18 +4,26 @@ properties:
     type:
       - string
       - 'null'
+    format: uri-reference
     description: |-
-      Use with the `after` query parameter to load the next page of data.
+      Path of the next page, relative to the API server URL.
+      Append the value to the server URL to get the next page.
+      The path keeps the query parameters of the request and sets `after` to the cursor of the next page.
       When `null`, there is no next page.
-      The cursor is opaque and internal structure is subject to change.
+    examples:
+      - /menu?limit=10&after=G0EAAIyUqm8V
   previousPage:
     type:
       - string
       - 'null'
+    format: uri-reference
     description: |-
-      Use with the `before` query parameter to load the previous page of data.
+      Path of the previous page, relative to the API server URL.
+      Append the value to the server URL to get the previous page.
+      The path keeps the query parameters of the request and sets `before` to the cursor of the previous page.
       When `null`, there is no previous page.
-      The cursor is opaque and internal structure is subject to change.
+    examples:
+      - /menu?limit=10&before=G0EAAIyUqm8W
   limit:
     type: integer
     minimum: 1