You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refactor and expand the pagination extension documentation to clarify
configuration options. Added detailed explanations for modifiers-based
and operation-based pagination approaches with examples and attribute
definitions.
Copy file name to clipboardExpand all lines: docs/extensions/pagination.md
+56-32Lines changed: 56 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -51,49 +51,73 @@ components:
51
51
has_more: "$response.body#/next_page_url"
52
52
```
53
53
54
-
## Pagination Extension Attributes
54
+
## Pagination Extension Configuration
55
55
56
-
The following attributes are supported in the pagination extension. Most fields accept [OpenAPI Runtime Expressions](https://swagger.io/docs/specification/v3_0/links/#runtime-expression-syntax) or dot-separated paths to extract values from the request or response.
56
+
Pagination in apier can be configured in two main ways: **Modifiers-based Pagination** and **Operation-based Pagination**. Each approach is suited to different API designs and use cases.
| `reuse_previous_request` | boolean | If true, the next request reuses the previous request's parameters. |
61
-
| `modifiers` | array | List of request modifiers to update parameters for the next request. |
62
-
| `param` (modifier) | string | The request parameter to modify (e.g., `$request.query.next`). |
63
-
| `value` (modifier) | string | Runtime expression to extract the value for the modifier. |
64
-
| `result` | string | Runtime expression or path to extract the data results from the response. |
65
-
| `has_more` | string | Runtime expression that determines if additional pages are available. If the evaluated result is `false` or empty (such as `null`, `0`, or `""`), pagination will stop. |
58
+
> 🧙♂️ **Using Dynamic Expressions**: Most pagination attributes accept [Dynamic Expressions](./expressions.md), which are a superset of OpenAPI Runtime Expressions. They allow you to extract and manipulate values from the request or response, combine multiple expressions, and perform advanced evaluations.
66
59
67
-
### Dynamic Expressions
60
+
### 1. Modifiers-based Pagination
68
61
69
-
[OpenAPI Runtime Expressions](https://swagger.io/docs/specification/v3_0/links/#runtime-expression-syntax) allow you to dynamically extract values from the request or response. In pagination configurations, they are used to specify how to retrieve the next page's cursor or URL, identify the result set, and determine if more pages are available, among other uses.
62
+
Use this approach when you need to update the parameters of the next request based on the previous response or request. Modifiers allow you to dynamically adjust query parameters, headers, or other request fields to fetch the next page.
70
63
71
-
In addition to the standard OpenAPI runtime expressions, apier also supports some additional features:
72
-
- **Dot-separated paths** (e.g., `#cursors.next`) provide a convenient way to access fields in the response body. These paths must always begin with a `#`.
73
-
- **Curly braces** can be used to include multiple runtime expressions in a single field (e.g., `/books/{$request.path.book_id}/authors/{$request.path.author_id}`).
74
-
- Expressions that don’t start with `$` or `#` are treated as literal strings.
75
-
- `$eval`allows for more complex evaluations, enabling the use of expressions that can manipulate or combine values from the request or response.
| `reuse_previous_request` | boolean | False | If true, the next request reuses the previous request's parameters. |
67
+
| `modifiers` | array | False | List of request modifiers to update parameters for the next request. Each modifier specifies which parameter to update and how to extract its new value. |
68
+
| `result` | string | True | [Dynamic Expression](./expressions.md) or path to extract the data results from the response. |
69
+
| `has_more` | string | True | [Dynamic Expression](./expressions.md) that determines if additional pages are available. If the evaluated result is `false` or empty, pagination will stop. |
76
70
77
-
Check the [Dynamic Expressions documentation](./expressions.md) for more details on how to use these expressions effectively.
71
+
If `reuse_previous_request` is not set, the next request will default to the same URL and method as the previous one, unless the modifiers specify otherwise.
78
72
79
-
### Request Modifiers
73
+
Modifiers define how to update the next request based on the previous response. Each modifier specifies which request parameter to change and how to compute its new value:
80
74
81
-
Request modifiers let you update request parameters for the next page based on values from the previous request or response. Modifiers are defined as an array of objects, each specifying a parameter to modify and the value to set it to.
82
-
- **param**: The request parameter to modify (e.g., `$request.query.next`). Here, `$request` refers to the request being prepared to fetch the next page.
83
-
- **value**: A runtime expression that extracts the value from the previous response or request. This value will be used to update the specified parameter for the next request. In this context, `$response` refers to the response from the previous request, and `$request` refers to the previous request.
| `param` | string | The request parameter to modify (e.g., `$request.query.next`). |
78
+
| `value` | string | [Dynamic Expression](./expressions.md) to extract the value for the modifier. |
84
79
85
-
The following example shows how to use a runtime expression to extract the next cursor value from the response body (`$response.body#/cursors/next`) and use it to update the `next` query parameter (`$request.query.next`) for the next request:
80
+
**Example:**
81
+
```yaml
82
+
x-pagination:
83
+
next:
84
+
reuse_previous_request: true
85
+
modifiers:
86
+
- param: $request.query.page
87
+
value: "$response.body#/next_page"
88
+
result: "#results"
89
+
has_more: "$response.body#/next_page"
90
+
```
91
+
92
+
### 2. Operation-based Pagination
93
+
94
+
Use this approach when the next page should be fetched by invoking a different or specific OpenAPI operation, rather than modifying the current request.
86
95
96
+
This pagination mode could be useful for non-standard pagination strategies where the next page is determined by a separate operation.
| `operation_id` | string | Yes | Defines the OpenAPI operation to fetch the next page. |
101
+
| `parameters` | array | No | Parameters to pass to the operation. This allows you to specify any parameters required by the operation, such as path or query parameters. |
102
+
| `result` | string | Yes | [Dynamic Expression](./expressions.md) or path to extract the data results from the response. |
103
+
| `has_more` | string | Yes | [Dynamic Expression](./expressions.md) that determines if additional pages are available. If the evaluated result is `false` or empty, pagination will stop. |
104
+
105
+
Parameters can be specified to pass values to the operation. If the operation requires specific parameters, they need to be defined here or the operation will fail.
0 commit comments