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/27741/api-d6d396f2cd22488c525a27934442252e8901a6b8.log

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

Stop reason: All reproducible response-validation specification errors in the log were fixed (6 unique error signatures across 3 schema files). Every remaining error in the log is either a known false positive, an intentional malformed-request test, or an internal/out-of-scope endpoint, so no further spec fixes are possible.

This PR is stacked on fix-spec-errors-from-staging, which already carries the fixes for errors that cannot be reproduced in the PR test environment.

Detailed changes description

Error fixes

Nullable buildTag on Actor version endpoints

• Files: apify-api/openapi/components/schemas/actors/Version.yaml:28
• Error: Response OpenAPI validation error {"url":"/v2/actors/{actorId}","method":"GET","statusCode":200,"errors":[{"message":"must be string","errorCode":"type.openapi.validation","path":"/response/data/versions/{n}/buildTag"}]} — also raised on GET /v2/actors/{actorId}/versions (/items/{n}/buildTag), POST /v2/actors/{actorId}/versions, GET /v2/actors/{actorId}/versions/{versionNumber} and PUT /v2/actors/{actorId}/versions/{versionNumber} (/data/buildTag).
• Root cause: A version created without a build tag stores and returns buildTag: null. The request schema already allows null, the value round-trips unchanged through the create/get/update handlers, but Version.yaml declared buildTag as a non-nullable string. Changed to type: [string, "null"].
• Reference: https://github.com/apify/apify-core/tree/db6c2e4b52c836e0bb45b2e22384c59b66024726/tests/integration/tests/actor/actors.openapi_response_validation.js#L44

Reduced GET /v2/users/me response from an Actor run

• Files: apify-api/openapi/components/schemas/users/UserPrivateInfo.yaml:2, apify-api/openapi/components/schemas/users/Plan.yaml:2
• Error: Response OpenAPI validation error {"url":"/v2/users/me","method":"GET","statusCode":200,"errors":[{"message":"must have required property 'id'","path":"/response/data/id"}, ... 'email','createdAt','profile', and every required field of plan]}
• Root cause: When /v2/users/me is accessed from an Actor run without full access, the handler deletes id, email, profile, createdAt and the full plan object, then re-adds plan containing only availableProxyGroups. Those properties were all marked required in the spec. Removed id, email, profile, createdAt from UserPrivateInfo.required and reduced Plan.required to only availableProxyGroups (the single field guaranteed in the reduced response).
• Reference: https://github.com/apify/apify-core/tree/db6c2e4b52c836e0bb45b2e22384c59b66024726/src/api/src/routes/users/user.ts#L43

Optional/nullable description and userFullName on store Actor listings

• Files: apify-api/openapi/components/schemas/store/StoreListActor.yaml:2 (required), :24 (userFullName), :26 (description)
• Error: Response OpenAPI validation error {"url":"/v2/store","method":"GET","statusCode":200,"errors":[{"message":"must have required property 'description'","path":"/response/data/items/{n}/description"},{"message":"must have required property 'userFullName'","path":"/response/data/items/{n}/userFullName"},{"message":"must be string","errorCode":"type.openapi.validation","path":"/response/data/items/{n}/userFullName"}]}
• Root cause: GET /v2/store (store_get) returns StoreListActor items where neither field is guaranteed. In the store index both fields are set from the owner's profile and become null when the owner has no public profile, and userFullName is optional in the StoreActor type. The spec marked both as required and typed them as non-nullable string. Removed userFullName and description from StoreListActor.required and changed both to type: [string, "null"].
• Reference: https://github.com/apify/apify-core/tree/db6c2e4b52c836e0bb45b2e22384c59b66024726/src/packages/actor-server/src/actors/actors_store_index.server.ts#L368 ; https://github.com/apify/apify-core/tree/db6c2e4b52c836e0bb45b2e22384c59b66024726/src/packages/types/src/actor_store.ts#L40 ; https://github.com/apify/apify-core/tree/db6c2e4b52c836e0bb45b2e22384c59b66024726/src/packages/types/src/actor.ts#L299

Issues

Partially implements: #2286

[apify-service-account]

✅ Preview for this PR (commit 3f7e922) is ready at https://pr-2707.preview.docs.apify.com (see action run).

[apify-service-account]

Important

Action required — @Pijukatel please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#910

• Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
• You can ask for review and help from the Tooling team if needed.

[janbuchar]

It would be nice to explain when these two can be missing/null, like in the Version schema