docs(openapi): Improve storage endpoints

[Pijukatel]

Summary

• Create reusable error response schemas
• Use granular 404 errors
• Autogenerate examples if possible
• Move unique examples closer to the schema definition
• Delete duplicate examples
• Extract and re-use non-unique parameters
• Fix non-working API docs client examples:
  • https://docs.apify.com/api/v2/request-queue-requests-batch-delete
  • https://docs.apify.com/api/v2/key-value-store-record-put

Motivation

• Preparation for adding undocumented redispatch endpoints, which will re-use the error schemas and parameters.
• Properly document different 404 errors returnable by the endpoint. This will give the user a better idea about potential failures.
• Make the specification more maintainable

Issues

Partially implements: #2286

---

Note

Medium Risk
Primarily a documentation/spec refactor, but it changes documented response codes/payloads (notably requestQueue_requests_batch_delete and multiple new 404 schemas), which could impact generated clients and integrations relying on the OpenAPI contract.

Overview
Improves the storage OpenAPI spec by extracting reusable query/path parameters into PaginationParameters.yaml and StorageParameters.yaml, then updating dataset, key-value store, and request-queue paths to reference them and removing duplicated inline parameter definitions.

Adds reusable storage error schemas in StorageErrors.yaml and updates endpoints to return documented 404 responses (including oneOf variants where multiple “not found” cases apply, e.g. store vs record, queue vs request).

Cleans up examples by moving endpoint examples into the relevant schema definitions (and removing duplicates), adds missing schema-level examples for several responses, and fixes/updates documentation for key-value store record uploads (optional Content-Encoding with gzip/deflate/br) and request-queue batch delete (documents JSON request body and a 200 response with BatchDeleteResponse).

^{Written by Cursor Bugbot for commit 9eb55b1. Configure here.}

[apify-service-account]

Preview for this PR was built for commit a7d23f7d and is ready at https://pr-2314.preview.docs.apify.com!

[apify-service-account]

Preview for this PR was built for commit 09f5a951 and is ready at https://pr-2314.preview.docs.apify.com!

[apify-service-account]

Preview for this PR was built for commit 1dd60e60 and is ready at https://pr-2314.preview.docs.apify.com!

[Copilot]

Pull request overview

This PR improves the OpenAPI specification for Apify's storage endpoints (datasets, key-value stores, and request queues) by extracting reusable parameter definitions and error schemas, removing duplicate examples, adding granular 404 error responses, and fixing API documentation issues (such as the batch delete response code and Content-Encoding header).

Changes:

• Extract shared parameters (storage IDs, pagination, client keys, etc.) into StorageParameters.yaml and PaginationParameters.yaml component files, replacing inline definitions across all storage endpoints.
• Create reusable 404 error schemas in StorageErrors.yaml and add 404 responses to all storage endpoints with appropriate error types (including oneOf for endpoints where multiple resources could be not found).
• Move examples from inline allOf/duplicate locations into their respective schema definitions, and fix the batch delete endpoint (response code 204→200, added requestBody with new RequestDraftKeyOnly schema, Content-Encoding header corrections).

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
components/parameters/StorageParameters.yaml	New shared parameter definitions for storage IDs, keys, client keys, lock, forefront, and signature
components/parameters/PaginationParameters.yaml	New shared pagination parameters (offset, limit, desc, unnamed)
components/schemas/common/errors/StorageErrors.yaml	New reusable 404 error schemas for each storage type
components/schemas/common/PaginationResponse.yaml	Adjusted example counts from 2 to 1
components/schemas/request-queues/RequestDraftKeyOnly.yaml	New schema for batch delete request body items
components/schemas/request-queues/Request.yaml	Moved example to schema level
components/schemas/request-queues/ListOfRequestsResponse.yaml	Moved example to schema level
components/schemas/request-queues/HeadResponse.yaml	Moved example to schema level
components/schemas/request-queues/HeadAndLockResponse.yaml	Moved example to schema level
components/schemas/request-queues/BatchAddResponse.yaml	Moved example to schema level
components/schemas/key-value-stores/ListOfKeysResponse.yaml	Moved example to schema level
components/schemas/key-value-stores/ListOfKeyValueStoresResponse.yaml	Simplified to direct $ref, removed inline example
components/schemas/datasets/PutItemResponseError.yaml	Moved example to schema level
components/schemas/datasets/DatasetStatistics.yaml	Moved example to schema level
components/schemas/datasets/DatasetListItem.yaml	Added examples for actId and actRunId
paths/request-queues/*.yaml (7 files)	Replaced inline params with $refs, removed duplicate examples, added 404 responses
paths/key-value-stores/*.yaml (4 files)	Replaced inline params with $refs, removed duplicate examples, added 404 responses
paths/datasets/*.yaml (4 files)	Replaced inline params with $refs, removed duplicate examples, added 404 responses

[apify-service-account]

Preview for this PR was built for commit 4786ee9d and is ready at https://pr-2314.preview.docs.apify.com!

[apify-service-account]

Preview for this PR was built for commit 9eb55b1d and is ready at https://pr-2314.preview.docs.apify.com!

[apify-service-account]

Preview for this PR was built for commit 28b6f905 and is ready at https://pr-2314.preview.docs.apify.com!

[apify-service-account]

Preview for this PR was built for commit 9eb55b1d and is ready at https://pr-2314.preview.docs.apify.com!