docs(openapi): Add missing descriptions to Update Actor endpoint

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

@@ -1,7 +1,9 @@
 title: BuildTag
 type: [object, "null"]
+description: The name of the build tag.
 required:
   - buildId
 properties:
   buildId:
     type: string
+    description: The ID of the build to assign to the tag.

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

@@ -5,29 +5,37 @@ properties:
     type: [string, "null"]
     pattern: ^([0-9]|[1-9][0-9])\.([0-9]|[1-9][0-9])$
     examples: ["0.0"]
+    description: The version number of the Actor. Must be a dot-separated sequence of numbers.
   sourceType:
     anyOf:
       - $ref: ./VersionSourceType.yaml
       - type: "null"
+    description: Where the source code of the version lives.
   envVars:
-    type: [array, "null"]
-    items:
-      $ref: ./EnvVarRequest.yaml
-    description: ""
+    anyOf:
+      - type: array
+        items:
+          $ref: ./EnvVar.yaml
+      - type: "null"
+    description: Environment variables for the version.
   applyEnvVarsToBuild:
     type: [boolean, "null"]
     examples: [false]
+    description: Whether to inject the environment variables at build time.
   buildTag:
     type: [string, "null"]
     examples: [latest]
+    description: The tag name to apply to a successful build of this version. Can be `null` when the version has no build tag.
   sourceFiles:
     $ref: ./VersionSourceFiles.yaml
+    description: Applies when the `sourceType` is `SOURCE_FILES`. Represents the Actor's
+      file structure as an array of files and folders.
   gitRepoUrl:
     type: [string, "null"]
-    description: URL of the Git repository when sourceType is GIT_REPO.
+    description: URL of the Git repository to clone the source code from. Applies when the `sourceType` is `GIT_REPO`.
   tarballUrl:
     type: [string, "null"]
-    description: URL of the tarball when sourceType is TARBALL.
+    description: URL of the tarball to download the source code from. Applies when the `sourceType` is `TARBALL`.
   gitHubGistUrl:
     type: [string, "null"]
-    description: URL of the GitHub Gist when sourceType is GITHUB_GIST.
+    description: URL of the GitHub Gist to clone the source code from. Applies when the `sourceType` is `GITHUB_GIST`.

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

@@ -3,26 +3,38 @@ type: object
 properties:
   name:
     type: string
-    examples: [MyActor]
+    examples: [instagram-scraper]
+    description: The identifier of the Actor. Use lowercase letters, numbers, and hyphens.
+      Spaces or special characters aren't allowed. Must be unique across your account.
   description:
     type: [string, "null"]
-    examples: [My favourite actor!]
+    examples: [This scraper extracts posts and comments from Instagram.]
+    description: Short description of the Actor, displayed in Apify Store and Console.
   isPublic:
     type: boolean
     examples: [false]
+    description: Whether the Actor is available to users in Apify Store. If `false`, the Actor is private
+      and only visible to you.
   actorPermissionLevel:
     anyOf:
       - $ref: ./ActorPermissionLevel.yaml
       - type: "null"
   seoTitle:
     type: [string, "null"]
-    examples: [My actor]
+    examples: [Free Instagram scraper]
+    description: Name of the Actor to display by search engines such as Google. Can be different
+      from the Actor's name displayed in Apify Store and Console. Recommended length is 40-50 characters.
   seoDescription:
     type: [string, "null"]
-    examples: [My actor is the best]
+    examples: [The best scraper for Instagram]
+    description: Description of the Actor to display by search engines such as Google.
+      Recommended length is 140-156 characters.
   title:
     type: [string, "null"]
-    examples: [My Actor]
+    examples: [Instagram scraper]
+    description: Human-readable name of the Actor, displayed in Apify Store and Console.
+      Can contain spaces and capital letters. Recommended length is 40-50 characters.
+      You can change this title without affecting the Actor's URL or SEO.
   restartOnError:
     type: boolean
     examples: [false]
@@ -31,61 +43,26 @@ properties:
     type: array
     items:
       $ref: ./CreateOrUpdateVersionRequest.yaml
-    description: ""
+    description: "An array of `Version` objects. Each object represents a specific version of the
+      Actor's source code: its location, builds, and environment configuration."
   pricingInfos:
     type: array
     items:
       $ref: ../actor-pricing-info/ActorRunPricingInfo.yaml
   categories:
     type: [array, "null"]
+    examples: [["SOCIAL_MEDIA"]]
     items:
       type: string
-    description: ""
+    description: A list of categories that best define the Actor. Reflected in Apify Store's search and filtering options.
   defaultRunOptions:
     anyOf:
       - $ref: ./DefaultRunOptions.yaml
       - type: "null"
+    description: The default settings applied to an Actor run. Can be overridden by the user.
   taggedBuilds:
     type: [object, "null"]
-    description: |
-      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`.
-
-      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
-        }
-        ```
+    description: A dictionary that maps tag names to specific builds. For details, see [Update build tags](#update-build-tags).
     additionalProperties:
       $ref: ./BuildTag.yaml
     example:
@@ -96,9 +73,13 @@ properties:
     anyOf:
       - $ref: ./ActorStandby.yaml
       - type: "null"
+    description: The configuration of the Actor's standby mode. For details, see [Standby mode](https://docs.apify.com/platform/actors/development/programming-interface/standby).
   exampleRunInput:
     anyOf:
       - $ref: ./ExampleRunInput.yaml
       - type: "null"
+    description: Sample input payload that demonstrates what a typical run input for an Actor
+      looks like. Used when no explicit input for a run is provided.
   isDeprecated:
     type: [boolean, "null"]
+    description: Whether the Actor is deprecated.

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

@@ -102,26 +102,65 @@ put:
     - Actors
   summary: Update Actor
   description: |
-    Updates settings of an Actor using values specified by an Actor object
-    passed as JSON in the POST payload.
-    If the object does not define a specific property, its value will not be
-    updated.
+    Updates an Actor's settings with the values specified in an `Actor` object
+    passed as JSON in the POST payload. Only the fields specified in the request body are updated.
 
-    The response is the full Actor object as returned by the
-    [Get Actor](#/reference/actors/actor-object/get-actor) endpoint.
+    Returns the full `Actor` object, the same as the
+    [Get Actor](/api/v2/act-get) endpoint.
 
-    The request needs to specify the `Content-Type: application/json` HTTP header!
+    In the HTTP request, set the `Content-Type` header to `application/json`.
 
-    When providing your API authentication token, we recommend using the
-    request's `Authorization` header, rather than the URL. ([More
-    info](#/introduction/authentication)).
+    ### Authentication
+
+    To provide the authentication token, we recommend using the request's
+    `Authorization` header, rather than the URL. For details,
+    see [Authentication](/api/v2/getting-started#authentication).
+
+    ### Make an Actor public
+
+    To make your Actor [public](https://docs.apify.com/platform/actors/publishing):
+    - Set `isPublic` to `true`.
+    - Provide `title` and `categories`. For reference, see [constants from the `apify-shared-js`
+    package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471)
+
+    ### Update build tags
+
+    To change tags assigned to Actor builds, use the `taggedBuilds` object. It's a dictionary that maps tag names
+    to specific builds, where:
+    - the key is the tag name, for example `latest` or `beta`
+    - the value is either `null` or an object with a build ID
+
+    Changing tags is a patch operation. Only the tags that you provide in this object are updated.
+
+    Note that you can assign multiple tags to a single build, but you can't assign the same tag to multiple builds.
+
+    - To create or reassign a tag, provide the tag name with a build ID. For example, to assign
+    the `latest` tag to a build, use:
+
+    ```json
+    {
+      "latest": { "buildId": "z2EryhbfhgSyqj6Hn" }
+    }
+    ```
+
+    - To remove a tag from a build, provide the tag name with a `null` value. For example, to remove the `beta` tag, use:
+
+    ```json
+    {
+      "beta": null
+    }
+    ```
+
+    - You can perform multiple actions at once. The following example reassigns `latest`
+    and removes `beta`, while preserving other existing tags:
+
+    ```json
+    {
+      "latest": { "buildId": "z2EryhbfhgSyqj6Hn" },
+      "beta": null
+    }
+    ```
 
-    If you want to make your Actor
-    [public](https://docs.apify.com/platform/actors/publishing) using `isPublic:
-    true`, you will need to provide the Actor's `title` and the `categories`
-    under which that Actor will be classified in Apify Store. For this, it's
-    best to use the [constants from our `apify-shared-js`
-    package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471).
   operationId: act_put
   parameters:
     - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId"
@@ -289,7 +328,7 @@ delete:
   tags:
     - Actors
   summary: Delete Actor
-  description: Deletes an Actor.
+  description: Deletes an Actor with the specified ID.
   operationId: act_delete
   parameters:
     - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId"