refactor: improved documentation text

Author: danpoletaev

apify-api/openapi/components/tags.yaml

@@ -256,10 +256,10 @@
   x-parent-tag-name: Actors
   x-trait: 'true'
   description: |
-    To obtain the OpenAPI schema for actor builds, two similar endpoints are available:
+    Get the OpenAPI specification for Actor builds. Two similar endpoints are available:
 
-    - [First Endpoint](/api/v2/act-openapi-specification-get): Requires both `actorId` and `buildId`. You can pass `default` instead of buildId to retrieve the OpenAPI schema for the default actor build.
-    - [Second Endpoint](/api/v2/actor-build-openapi-specification-get): Requires only `buildId`.
+    - [First endpoint](/api/v2/act-openapi-specification-get): Requires both `actorId` and `buildId`. Use `default` as the `buildId` to get the OpenAPI schema for the default Actor build.
+    - [Second endpoint](/api/v2/actor-build-openapi-specification-get): Requires only `buildId`.
 - name: Actor tasks
   x-displayName: Actor tasks
   x-legacy-doc-urls:
@@ -562,10 +562,10 @@
   x-parent-tag-name: Actor builds
   x-trait: 'true'
   description: |
-    To obtain the OpenAPI schema for actor builds, two similar endpoints are available:
+    Get the OpenAPI specification for Actor builds. Two similar endpoints are available:
 
-    - [First Endpoint](/api/v2/act-openapi-specification-get): Requires both `actorId` and `buildId`. You can pass `default` instead of buildId to retrieve the OpenAPI schema for the default actor build.
-    - [Second Endpoint](/api/v2/actor-build-openapi-specification-get): Requires only `buildId`.
+    - [First endpoint](/api/v2/act-openapi-specification-get): Requires both `actorId` and `buildId`. Use `default` as the `buildId` to get the OpenAPI schema for the default Actor build.
+    - [Second endpoint](/api/v2/actor-build-openapi-specification-get): Requires only `buildId`.
 - name: Key-value stores
   x-displayName: Key-value stores
   x-legacy-doc-urls:

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi-specification.yaml

@@ -3,19 +3,18 @@ get:
     - Actor builds/Get OpenAPI specification
   summary: Get OpenAPI specification
   description: |
-
-    > **You can also use a [similar endpoint](/api/v2/act-openapi-specification-get)**
-    > from the `acts` namespace to retrieve the OpenAPI specification for a build.
-
-    This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the build.
+    Get the OpenAPI specification for a specific Actor build.
+    Authentication is based on the build's unique ID. No authentication token is required.
+    
+    **Note**: You can also use the `/api/v2/act-openapi-specification-get` endpoint to get the OpenAPI specification for a build.
   operationId: actorBuild_openapiSpecification_get
   security:
     - apiKeyActorBuilds: []
     - httpBearerActorBuilds: []
   parameters:
     - name: buildId
       in: path
-      description: 'ID of the build you want to get, found in the build''s `Info` tab.'
+      description: ID of the build you want to get, found in the build's `Info` tab.
       required: true
       style: simple
       schema:

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

@@ -3,13 +3,12 @@ get:
     - Actors/Get OpenAPI specification
   summary: Get OpenAPI specification
   description: |
-
-    > **You can also use a [similar endpoint](/api/v2/actor-build-openapi-specification-get)**
-    > from the `actor-builds` namespace to retrieve the OpenAPI specification for a build.
-
-    To fetch the default actor build, simply pass `default` in place of `buildId`.
-
-    This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the build.
+    Get the OpenAPI specification for a specific Actor build.
+    
+    To fetch the default Actor build, simply pass `default` as the `buildId`.
+    Authentication is based on the build's unique ID. No authentication token is required.
+    
+    **Note**: You can also use the `/api/v2/actor-build-openapi-specification-get` endpoint to get the OpenAPI specification for a build.
   operationId: act_openapiSpecification_get
   security:
     - apiKeyActorBuilds: []
@@ -25,7 +24,7 @@ get:
         example: janedoe~my-actor
     - name: buildId
       in: path
-      description: 'ID of the build you want to get, found in the build''s `Info` tab. Pass `default` for default actor build.'
+      description: ID of the build you want to get, found in the build's `Info` tab. Pass `default` for default Actor build.
       required: true
       style: simple
       schema: