api-platform / api-platform/core
Add Example Value for 'page' Parameter and Clarify Handling of Empty 'page' Values
- 主要語言
- PHP
- 星號
- 2.6k
- 分支
- 980
- 平均合併
- 2 天 5 小時
- 30 天內合併 PR
- 48
描述
## 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.
貢獻指南
評估
這個 Issue 還沒有評估資料。