api-platform / api-platform/core
Add Example Value for 'page' Parameter and Clarify Handling of Empty 'page' Values
- Dominant language
- PHP
- Stars
- 2.6k
- Forks
- 980
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 48
Description
## Description
Currently, the `page` query parameter in API Platform OpenAPI documentation is defined with a `default` value of `1` but lacks an `example` value. This absence can lead to issues with tools like ApiDog, which may import and activate the `page` parameter without an example.

Resulting in requests such as: `url.org?page=` by default after import.
Such requests cause failures ‘Page should not be less than 1‘ due to the empty `page` parameter.
## Proposed Solution
### 1. Add an Example Value to the `page` Parameter
To align with the [OpenAPI specification](https://swagger.io/docs/specification/v3_0/describing-parameters/#default-parameter-values) and improve compatibility with tools that consume OpenAPI, it is recommended to add an `example` value of `1` to the `page` parameter. This can be achieved by modifying the parameter definition as follows:
```php
$parameters[] = new Parameter(
$this->paginationOptions->getPaginationPageParameterName(),
'query',
'The collection page number',
false,
false,
true,
['type' => 'integer', 'default' => 1],
example: 1
);
```
### 2. Define Behavior for Empty page Parameter Values
Clarify how API Platform should handle cases where the page parameter is provided with an empty value. There are two potential approaches:
- Fallback to Default: Treat an empty page value as if the default value (1) was provided.
- Return Bad Request (current behavior): Respond with a 400 Bad Request status, indicating that the page parameter should not be empty.
----
I am open to working on a PR to implement this change if the proposal is accepted.
Contributor guide
Assessment
This issue has not been assessed yet.