Add Example Value for 'page' Parameter and Clarify Handling of Empty 'page' Values
Maintainers usually reply within 1 day
@soyuka is already working on this.
Since May 13, 2025.
Assessment
This issue has not been assessed yet.
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 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.
- Dominant language
- PHP
- Stars
- 2.6k
- Forks
- 989
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 102
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from api-platform/core
-
JSON:API: resource schemas (`*.jsonapi`) have `properties` but no `type: object`Possibly taken @ousamabenyounes claimed this 2 days ago. Open
Difficulty 2/5 Under an hour Newbie friendliness 80/100
api-platform/core#8701 ·
Maintainers usually reply within 1 day
-
JSON:API: `JsonApiCollectionBaseSchemaNoPagination` declares `data` as `type: array` without `items`Open
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
api-platform/core#8699 ·
Maintainers usually reply within 1 day
-
api:openapi:export --spec-version=3.0.0 outputs `webhooks`, which is invalid in OpenAPI 3.0Possibly taken A pull request linked to this issue is open or already merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
api-platform/core#8690 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
api-platform/core#8680 ·
Maintainers usually reply within 1 day
-
Difficulty 3/5 1-2 days Newbie friendliness 68/100
api-platform/core#8725 ·
Maintainers usually reply within 1 day
All issues in api-platform/core
Similar issues
-
InvoiceSettled is answered 200 when the invoice cannot be re-fetched, so BTCPay never redelivers itOpen
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
btcpayserver/woocommerce-greenfield-plugin#93 ·
Maintainers usually reply within 1 day
-
kind/bug status/triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
🐛 [Bug] Bulk CSV import stores hide_from_combined_view=FALSE as a string, which hides every account from Sent, Junk, Trash and DraftsPossibly taken @exSnake claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
opnsense/core#11052 · 1 comment ·
Maintainers usually reply within 1 day
-
needs triage
Difficulty 2/5 1-3 hours Newbie friendliness 66/100