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

apify-api/openapi/components/parameters/runAndBuildParameters.yaml

@@ -1,12 +1,12 @@
 actorId:
   name: actorId
   in: path
-  description: Actor ID or a tilde-separated owner's username and Actor name.
+  description: Actor ID or the username of the Actor owner and the Actor name, separated by a tilde (`~`).
   required: true
   style: simple
   schema:
     type: string
-    example: janedoe~my-actor
+    example: compass~google-maps-extractor
 
 actorTaskId:
   name: actorTaskId

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

@@ -15,42 +15,51 @@ properties:
   id:
     type: string
     examples: [zdc3Pyhyz3m8vjDeM]
+    description: The ID of the Actor.
   userId:
     type: string
     examples: [wRsJZtadYvn4mBZmm]
+    description: The ID of the user who owns the Actor.
   name:
     type: string
-    examples: [MyActor]
+    examples: [google-search-extractor]
+    description: The name of the Actor.
   username:
     type: string
-    examples: [jane35]
+    examples: [compass]
+    description: The username of the Actor owner.
   description:
     type: [string, "null"]
-    examples: [My favourite actor!]
+    examples: [Extract data from hundreds of places fast.]
+    description: Short description of the Actor, displayed in Apify Store and Console.
   restartOnError:
     type: boolean
     examples: [false]
     deprecated: true # Use defaultRunOptions.restartOnError instead
   isPublic:
     type: boolean
     examples: [false]
+    description: Whether the Actor is available to users in Apify Store.
   actorPermissionLevel:
     $ref: ./ActorPermissionLevel.yaml
   createdAt:
     type: string
     format: date-time
     examples: ["2019-07-08T11:27:57.401Z"]
+    description: The date and time the Actor was created. Follows the ISO 8601 format.
   modifiedAt:
     type: string
     format: date-time
     examples: ["2019-07-08T14:01:05.546Z"]
+    description: The date and time the Actor was last modified. Follows the ISO 8601 format.
   stats:
     $ref: ./ActorStats.yaml
   versions:
     type: array
     items:
       $ref: ./Version.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:
@@ -64,12 +73,15 @@ properties:
   isDeprecated:
     type: [boolean, "null"]
     examples: [false]
+    description: Whether the Actor is deprecated.
   deploymentKey:
     type: string
     examples: [ssh-rsa AAAA ...]
+    description: The Actor's public SSH key, used as a deployment key for private Git repositories.
   title:
     type: [string, "null"]
-    examples: [My Actor]
+    examples: [Google Search Extractor]
+    description: Human-readable name of the Actor, displayed in Apify Store and Console.
   taggedBuilds:
     anyOf:
       - $ref: ./TaggedBuilds.yaml
@@ -80,36 +92,49 @@ properties:
       - type: "null"
   readmeSummary:
     type: string
-    description: A brief, LLM-generated readme summary
+    description: An AI-generated Markdown summary of the Actor's README, optimized for search and
+      AI agents. Contains an overview and a list of use cases. Generated only for public Actors.
   seoTitle:
     type: [string, "null"]
     examples: [Web 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.
   seoDescription:
     type: [string, "null"]
     examples: ["Crawls websites using Chrome and extracts data from pages using JavaScript."]
+    description: Description of the Actor to display by search engines such as Google.
   pictureUrl:
     type: [string, "null"]
     examples: ["https://apify-image-uploads-prod.s3.amazonaws.com/.../actor-picture.png"]
+    description: URL of the Actor's icon, displayed on the Actor's page in Apify Store and Console.
   standbyUrl:
     type: [string, "null"]
-    examples: ["https://my-actor.apify.actor"]
+    examples: ["https://jane35--my-actor.apify.actor"]
+    description: |
+      URL for sending requests to the Actor in Standby mode.
+      `null` if the Standby mode isn't enabled.
   notice:
-    type: [string, "null"]
-    examples: [NONE]
+    $ref: ./ActorNotice.yaml
   categories:
     type: array
     items:
       type: string
     examples: [["DEVELOPER_TOOLS", "OPEN_SOURCE"]]
+    description: A list of categories that best define the Actor. Reflected in Apify Store's search and filtering options.
   isCritical:
     type: boolean
     examples: [false]
+    description: Whether the Actor is maintained by Apify.
   isGeneric:
     type: boolean
     examples: [false]
+    description: Whether the Actor is intended for developers. Set by Apify.
   isSourceCodeHidden:
     type: boolean
-    examples: [false]
+    default: true
+    examples: [true]
+    description: Whether the Actor's source files are hidden on its detail page.
   hasNoDataset:
     type: boolean
     examples: [false]
+    description: Whether the Actor stores results in a dataset. Set by Apify.

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

@@ -0,0 +1,9 @@
+title: ActorNotice
+type: [string, "null"]
+description: A warning displayed on the Actor's page in Apify Store and Console.
+  Can be set by the Actor's developer or automatically by Apify's quality checks.
+enum:
+  - NONE
+  - RESIDENTIAL_PROXY_REQUIRED
+  - UNDER_MAINTENANCE
+examples: [UNDER_MAINTENANCE]

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

@@ -1,56 +1,77 @@
 title: ActorStats
 type: object
+description: Usage statistics and Apify Store metrics for the Actor.
 properties:
   totalBuilds:
     type: integer
     examples: [9]
+    description: The total number of builds of the Actor.
   totalRuns:
     type: integer
     examples: [16]
+    description: The total number of runs of the Actor.
   totalUsers:
     type: integer
     examples: [6]
+    description: The total number of Actor users, including its owner.
   totalUsers7Days:
     type: integer
     examples: [2]
+    description: The number of active users of the Actor in the last 7 days.
   totalUsers30Days:
     type: integer
     examples: [6]
+    description: The number of active users of the Actor in the last 30 days.
   totalUsers90Days:
     type: integer
     examples: [6]
+    description: The number of active users of the Actor in the last 90 days.
   totalMetamorphs:
     type: integer
     examples: [2]
+    description: The total number of times a run of another Actor was
+      [metamorphed](https://docs.apify.com/platform/actors/development/programming-interface/metamorph)
+      into this Actor.
   lastRunStartedAt:
     type: string
     format: date-time
     examples: ["2019-07-08T14:01:05.546Z"]
+    description: The date and time the most recent run of the Actor started.
   actorReviewCount:
     type: integer
     examples: [69]
+    description: The number of reviews the Actor has received in Apify Store.
   actorReviewRating:
     type: number
     examples: [4.7]
+    description: The average rating of the Actor in Apify Store.
   bookmarkCount:
     type: integer
     examples: [1269]
+    description: The number of users who bookmarked the Actor in Apify Store.
   publicActorRunStats30Days:
     type: object
-    description: Run status counts over the past 30 days.
+    description: |
+     Run status counts from the last 30 days. Only for public Actors.
+     Excludes runs started by the Actor's owner.
     properties:
       ABORTED:
         type: integer
         examples: [2542]
+        description: The number of runs that were aborted.
       FAILED:
         type: integer
         examples: [1234]
+        description: The number of runs that failed.
       SUCCEEDED:
         type: integer
         examples: [732805]
+        description: The number of runs that succeeded.
       "TIMED-OUT":
         type: integer
         examples: [12556]
+        description: The number of runs that timed out.
       TOTAL:
         type: integer
         examples: [749137]
+        description: The total number of runs.

apify-api/openapi/components/schemas/store/StoreListActor.yaml

@@ -33,7 +33,7 @@ properties:
       - MARKETING
       - LEAD_GENERATION
   notice:
-    type: [string, "null"]
+    $ref: ../actors/ActorNotice.yaml
   pictureUrl:
     type: [string, "null"]
     format: uri

apify-api/openapi/components/tags.yaml

@@ -8,11 +8,13 @@
     - "#/reference/actors/actor-object"
     - "#tag/ActorsActor-object"
   description: |
-    The API endpoints in this section allow you to manage Apify Actors. For more details about Actors, refer to the [Actor documentation](https://docs.apify.com/platform/actors).
+    The API endpoints in this section allow you to manage [Apify Actors](https://docs.apify.com/platform/actors).
 
-    For API endpoints that require the `actorId` parameter to identify an Actor, you can provide either:
-    - The Actor ID (e.g., `HG7ML7M8z78YcAPEB`), or
-    - A tilde-separated combination of the Actor owner's username and the Actor name (e.g., `janedoe~my-actor`).
+    ## Identify an Actor
+
+    For API endpoints that require the `actorId` parameter, provide one of the following:
+    - The Actor ID. It's part of the Actor's URL in Apify Console: `https://console.apify.com/actors/<ACTOR_ID>`. For example, `reGe1ST3OBgYZSsZJ`.
+    - The username of the Actor owner plus the Actor name, separated by a tilde (`~`). For example, `apify~instagram-scraper`.
 
 - name: Actors/Actor versions
   x-displayName: Actor versions

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

@@ -2,7 +2,7 @@ get:
   tags:
     - Actors
   summary: Get Actor
-  description: Gets an object that contains all the details about a specific Actor.
+  description: Gets an object that contains all the details about the Actor with the specified ID.
   operationId: actor_get
   parameters:
     - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId"
@@ -18,9 +18,9 @@ get:
             data:
               id: zdc3Pyhyz3m8vjDeM
               userId: wRsJZtadYvn4mBZmm
-              name: MyActor
+              name: instagram-scraper
               username: jane35
-              description: My favourite Actor!
+              description: Extract data from Instagram.
               isPublic: false
               createdAt: "2019-07-08T11:27:57.401Z"
               modifiedAt: "2019-07-08T14:01:05.546Z"
@@ -68,7 +68,7 @@ get:
                 contentType: application/json; charset=utf-8
               isDeprecated: false
               deploymentKey: ssh-rsa AAAA ...
-              title: My Actor
+              title: Instagram Scraper
               taggedBuilds:
                 latest:
                   buildId: z2EryhbfhgSyqj6Hn