feat: update tagged builds API docs (#2018)

This PR updates the tagged builds API documentation to reflect the new
interface and the fix for an inherent race condition that was fixed in
apify/apify-core#23446.

---------

Co-authored-by: Tobiáš Potoček <[email protected]>

Author: lewis-wow

apify-api/openapi/components/schemas/actors/UpdateActorRequest.yaml

@@ -53,16 +53,48 @@ properties:
   taggedBuilds:
     type: object
     description: |
-      Object containing the Actor's tagged builds, where the key is the tag name (e.g., _latest_) and the value is an object containing the build ID.
-      The object you provide will completely overwrite all existing tagged builds for the Actor.
+      An object to modify tags on the Actor's builds. The key is the tag name (e.g., _latest_), and the value is either an object with a `buildId` or `null`.
 
-      - To create or reassign a tag: Include it in the object with the desired `buildId`.
-      - To remove a specific tag: Submit the object without that tag's key.
-      - To remove all tags: Provide an empty object: `{}`.
-      - If this field is omitted or `null`, the existing tags will not be changed.
+      This operation is a patch; any existing tags that you omit from this object will be preserved.
+
+      - **To create or reassign a tag**, provide the tag name with a `buildId`. e.g., to assign the _latest_ tag:
+
+         
+
+        ```json
+        {
+          "latest": {
+            "buildId": "z2EryhbfhgSyqj6Hn"
+          }
+        }
+        ```
+
+      - **To remove a tag**, provide the tag name with a `null` value. e.g., to remove the _beta_ tag:
+
+         
+
+        ```json
+        {
+          "beta": null
+        }
+        ```
+
+      - **To perform multiple operations**, combine them. The following reassigns _latest_ and removes _beta_, while preserving any other existing tags.
+
+         
+
+        ```json
+        {
+          "latest": {
+            "buildId": "z2EryhbfhgSyqj6Hn"
+          },
+          "beta": null
+        }
+        ```
     nullable: true
     additionalProperties:
       type: object
+      nullable: true
       required:
         - buildId
       properties:
@@ -71,3 +103,4 @@ properties:
     example:
       latest:
         buildId: z2EryhbfhgSyqj6Hn
+      beta: null

apify-api/openapi/paths/actors/acts@{actorId}.yaml

@@ -133,32 +133,53 @@ put:
       application/json:
         schema:
           $ref: "../../components/schemas/actors/UpdateActorRequest.yaml"
-        example:
-          name: MyActor
-          description: My favourite Actor!
-          isPublic: false
-          seoTitle: My Actor
-          seoDescription: My Actor is the best
-          title: My Actor
-          restartOnError: false
-          versions:
-            - versionNumber: '0.0'
-              sourceType: SOURCE_FILES
-              envVars:
-                - name: DOMAIN
-                  value: 'http://example.com'
-                  isSecret: false
-                - name: SECRET_PASSWORD
-                  value: MyTopSecretPassword123
-                  isSecret: true
-              applyEnvVarsToBuild: false
-              buildTag: latest
-              sourceFiles: []
-          categories: []
-          defaultRunOptions:
-            build: latest
-            timeoutSecs: 3600
-            memoryMbytes: 2048
+        examples:
+          common:
+            summary: 'Common example'
+            value:
+              name: MyActor
+              description: My favourite Actor!
+              isPublic: false
+              seoTitle: My Actor
+              seoDescription: My Actor is the best
+              title: My Actor
+              restartOnError: false
+              versions:
+                - versionNumber: '0.0'
+                  sourceType: SOURCE_FILES
+                  envVars:
+                    - name: DOMAIN
+                      value: 'http://example.com'
+                      isSecret: false
+                    - name: SECRET_PASSWORD
+                      value: MyTopSecretPassword123
+                      isSecret: true
+                  applyEnvVarsToBuild: false
+                  buildTag: latest
+                  sourceFiles: []
+              categories: []
+              defaultRunOptions:
+                build: latest
+                timeoutSecs: 3600
+                memoryMbytes: 2048
+          taggedBuildsCreateOrReassignTag:
+            summary: 'Create or reassign a build tag'
+            value:
+              taggedBuilds:
+                latest:
+                  buildId: 'z2EryhbfhgSyqj6Hn'
+          taggedBuildsRemoveTag:
+            summary: 'Remove a build tag'
+            value:
+              taggedBuilds:
+                latest: null
+          taggedBuildsMultipleOperations:
+            summary: 'Update multiple build tags at once'
+            value:
+              taggedBuilds:
+                latest:
+                  buildId: 'z2EryhbfhgSyqj6Hn'
+                beta: null
     required: true
   responses:
     '200':