docs(openapi): Autofix OpenAPI spec validation errors

[Pijukatel]

Summary

Autogenerated OpenAPI fixes suggestions based on validation errors generated from running API integration tests with OpenAPI validator turned on.

Error log: https://apify-pr-test-env-logs.s3.us-east-1.amazonaws.com/apify/apify-core/26280/api-e8976db3b5b2476d2f01af1a84d4268fc61e839f.log

apify-core version: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f

Stop reason: In progress - added 5 missing top-level endpoints and 12 storage sub-resource proxy endpoints under actor-runs.

Detailed changes description

Error fixes

1. Add GET /v2/actor-runs/{runId}/dataset endpoint

Files: apify-api/openapi/paths/actor-runs/actor-runs@{runId}@dataset.yaml:1, apify-api/openapi/openapi.yaml:555
Error: WARN Request OpenAPI validation error {"url":"/v2/actor-runs/{runId}/dataset","method":"GET","errors":[{"message":"not found","path":"/v2/actor-runs/{runId}/dataset"}]}
Root cause: The endpoint exists in apify-core (src/api/src/routes/actor_runs/run_dataset.ts) and proxies GET requests to /v2/datasets/{defaultDatasetId}, but had no OpenAPI path definition. Added GET operation returning DatasetResponse.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/routes/routes_config.ts#L724

2. Add GET /v2/actor-runs/{runId}/key-value-store endpoint

Files: apify-api/openapi/paths/actor-runs/actor-runs@{runId}@key-value-store.yaml:1, apify-api/openapi/openapi.yaml:557
Error: WARN Request OpenAPI validation error {"url":"/v2/actor-runs/{runId}/key-value-store","method":"GET","errors":[{"message":"not found","path":"/v2/actor-runs/{runId}/key-value-store"}]}
Root cause: The endpoint exists in apify-core (src/api/src/routes/actor_runs/run_key_value_store.ts) and proxies GET requests to /v2/key-value-stores/{defaultKeyValueStoreId}, but had no OpenAPI path definition. Added GET operation returning KeyValueStoreResponse.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/routes/routes_config.ts#L737

3. Add GET /v2/actor-runs/{runId}/log endpoint

Files: apify-api/openapi/paths/actor-runs/actor-runs@{runId}@log.yaml:1, apify-api/openapi/openapi.yaml:559
Error: WARN Request OpenAPI validation error {"url":"/v2/actor-runs/{runId}/log","method":"GET","errors":[{"message":"not found","path":"/v2/actor-runs/{runId}/log"}]}
Root cause: The endpoint exists in apify-core (src/api/src/routes/actor_runs/run_log.ts) and proxies GET requests to /v2/logs/{runId}, but had no OpenAPI path definition. Added GET operation returning text/plain log content with stream, download, and raw parameters.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/routes/routes_config.ts#L763

4. Add GET /v2/actor-runs/{runId}/request-queue endpoint

Files: apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue.yaml:1, apify-api/openapi/openapi.yaml:561
Error: WARN Request OpenAPI validation error {"url":"/v2/actor-runs/{runId}/request-queue","method":"GET","errors":[{"message":"not found","path":"/v2/actor-runs/{runId}/request-queue"}]}
Root cause: The endpoint exists in apify-core (src/api/src/routes/actor_runs/run_request_queue.ts) and proxies GET requests to /v2/request-queues/{defaultRequestQueueId}, but had no OpenAPI path definition. Added GET operation returning RequestQueueResponse.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/routes/routes_config.ts#L750

5. Add POST /v2/acts/{actorId}/validate-input endpoint

Files: apify-api/openapi/paths/actors/acts@{actorId}@validate-input.yaml:1, apify-api/openapi/openapi.yaml:523
Error: WARN Request OpenAPI validation error {"url":"/v2/acts/{actorId}/validate-input","method":"POST","errors":[{"message":"not found","path":"/v2/acts/{actorId}/validate-input"}]}
Root cause: The endpoint exists in apify-core (src/api/src/routes/actors/validate_input.ts) and validates Actor input against the build's input schema. Does not require authentication (security: []). Returns { valid: boolean }. Had no OpenAPI path definition.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/routes/actors/validate_input.ts#L85

6. Add actor-runs dataset sub-resource endpoints

Files: apify-api/openapi/paths/actor-runs/actor-runs@{runId}@dataset@items.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@dataset@statistics.yaml:1
Error: WARN Request OpenAPI validation error {"url":"/v2/actor-runs/{runId}/dataset/items","method":"GET","errors":[{"message":"not found","path":"/datasets/{datasetId}/items"}]}
Root cause: The actor-runs proxy forwards sub-resource requests via getRunRoute() in controllers.ts to /v2/datasets/{defaultDatasetId}/.... Added OpenAPI definitions for dataset/items (GET, HEAD, POST) and dataset/statistics (GET) mirroring the corresponding datasets endpoints.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/lib/controllers.ts#L37

7. Add actor-runs key-value-store sub-resource endpoints

Files: apify-api/openapi/paths/actor-runs/actor-runs@{runId}@key-value-store@keys.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@key-value-store@records.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@key-value-store@records@{recordKey}.yaml:1
Error: WARN Request OpenAPI validation error {"url":"/v2/actor-runs/{runId}/key-value-store/records/{recordKey}","method":"GET","errors":[{"message":"not found","path":"/key-value-stores/{storeId}/records/{recordKey}"}]}
Root cause: The actor-runs proxy forwards sub-resource requests via getRunRoute() to /v2/key-value-stores/{defaultKeyValueStoreId}/.... Added OpenAPI definitions for key-value-store/keys (GET), key-value-store/records (GET), and key-value-store/records/{recordKey} (GET, HEAD, PUT, POST, DELETE) mirroring the corresponding key-value-stores endpoints.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/lib/controllers.ts#L35

8. Add actor-runs request-queue sub-resource endpoints

Files: apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue@requests.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue@requests@batch.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue@requests@unlock.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue@requests@{requestId}.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue@head.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue@head@lock.yaml:1, apify-api/openapi/paths/actor-runs/actor-runs@{runId}@request-queue@requests@{requestId}@lock.yaml:1
Error: WARN Request OpenAPI validation error {"url":"/v2/actor-runs/{runId}/request-queue/requests/{requestId}","method":"GET","errors":[{"message":"not found","path":"/request-queues/{queueId}/requests/{requestId}"}]}
Root cause: The actor-runs proxy forwards sub-resource requests via getRunRoute() to /v2/request-queues/{defaultRequestQueueId}/.... Added OpenAPI definitions for all request-queue sub-resources: requests (GET, POST), requests/batch (POST, DELETE), requests/unlock (POST), requests/{requestId} (GET, PUT, DELETE), head (GET), head/lock (POST), and requests/{requestId}/lock (PUT, DELETE) mirroring the corresponding request-queues endpoints.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/lib/controllers.ts#L39

Refactoring

None.

Unfixed errors

False positives

Proxy middleware resolved paths for acts/runs/last and actor-tasks/runs/last sub-resources

Error: WARN Request OpenAPI validation error {"url":"/v2/acts/{actorId}/runs/last/dataset/items","method":"GET","errors":[{"message":"not found","path":"/datasets/{datasetId}/items"}]}
Root cause: The "last run" shortcut endpoints under /v2/acts/{actorId}/runs/last/ and /v2/actor-tasks/{taskId}/runs/last/ resolve through getRunRoute() and then proxy to storage/action endpoints with internal paths lacking the /v2/ prefix. The validator checks the resolved path which doesn't match any spec path. Affects abort, metamorph, reboot, dataset/items, key-value-store/records, log, and request-queue/head operations. Total: 11 errors.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/lib/controllers.ts#L7

/v2/openapi.json endpoint

Error: WARN Request OpenAPI validation error {"url":"/v2/openapi.json","method":"GET","errors":[{"message":"not found","path":"/openapi.json"}]}
Root cause: The /v2/openapi.json endpoint serves the OpenAPI spec itself. The validator resolves the path to /openapi.json (without /v2/ prefix), which doesn't match any spec path. This is a meta-endpoint that documents the API but isn't itself part of the API contract. Total: 2 errors.
Reference: https://github.com/apify/apify-core/tree/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/api/src/lib/api_server.ts

Potential API bugs

None identified.

Out of scope errors

None.

Issues

Partially implements: #2286

[apify-service-account]

A PR to update the Python client models has been created: apify/apify-client-python#714

This was automatically triggered by OpenAPI specification changes in this PR.

[apify-service-account]

The Python client model PR has been updated with the latest OpenAPI spec changes: apify/apify-client-python#714