api-platform / api-platform/core

Add Example Value for 'page' Parameter and Clarify Handling of Empty 'page' Values

未關閉
#7,015 1 則留言 0 個 reaction 已指派 1 人 已被 @soyuka 認領 在 GitHub 檢視
OpenAPI
主要語言
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.

![Image](https://github.com/user-attachments/assets/9d916572-7146-4c19-ba7d-2ef9b91a450a)

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 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。