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

[TheoD02]

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 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:

$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.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.