api-platform / api-platform/core

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

Open
#7,015 1 comment 0 reactions 1 assignee Claimed by @soyuka View on GitHub
OpenAPI
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.

![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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.