feat(api): added openapi endpoints documentation

Author: danpoletaev

apify-api/openapi/components/tags.yaml

@@ -251,6 +251,17 @@
     ```
 
     In order to save new items to the dataset, send HTTP POST request with JSON payload to the same URL.
+- name: Actors/Build OpenAPI specification
+  x-displayName: Build OpenAPI Specification
+  x-parent-tag-name: Actors
+  x-trait: 'true'
+  description: |
+    To obtain the OpenAPI schema 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`.
+  x-legacy-doc-urls:
+  - '#/reference/actors/openapi-specification'
 - name: Actor tasks
   x-displayName: Actor tasks
   x-legacy-doc-urls:
@@ -548,6 +559,17 @@
   - '#tag/Actor-buildsBuild-log'
   x-trait: 'true'
   description: Check out [Logs](#/reference/logs) for full reference.
+- name: Actor builds/Build OpenAPI specification
+  x-displayName: Build OpenAPI Specification
+  x-parent-tag-name: Actor builds
+  x-trait: 'true'
+  description: |
+    To obtain the OpenAPI schema 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`.
+  x-legacy-doc-urls:
+  - '#/reference/actor-builds/openapi-specification'
 - name: Key-value stores
   x-displayName: Key-value stores
   x-legacy-doc-urls:

apify-api/openapi/components/x-tag-groups.yaml

@@ -19,6 +19,7 @@
   - Actors/Metamorph run
   - Actors/Resurrect run
   - Actors/Last run object and its storages
+  - Actors/Build OpenAPI specification
 - name: Actor tasks
   tags:
   - Actor tasks
@@ -50,6 +51,7 @@
   - Actor builds/Delete build
   - Actor builds/Abort build
   - Actor builds/Build log
+  - Actor builds/Build OpenAPI specification
 - name: Key-value stores
   tags:
   - Key-value stores

apify-api/openapi/openapi.yaml

@@ -501,6 +501,8 @@ paths:
     $ref: 'paths/actors/acts@{actorId}@builds@{buildId}.yaml'
   '/v2/acts/{actorId}/builds/{buildId}/abort':
     $ref: 'paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml'
+  '/v2/acts/{actorId}/builds/{buildId}/openapi-specification':
+    $ref: 'paths/actors/acts@{actorId}@builds@{buildId}@openapi-specification.yaml'
   '/v2/acts/{actorId}/runs':
     $ref: 'paths/actors/acts@{actorId}@runs.yaml'
   '/v2/acts/{actorId}/run-sync':
@@ -553,6 +555,8 @@ paths:
     $ref: 'paths/actor-builds/actor-builds@{buildId}@abort.yaml'
   '/v2/actor-builds/{buildId}/log':
     $ref: 'paths/actor-builds/actor-builds@{buildId}@log.yaml'
+  '/v2/actor-builds/{buildId}/openapi-specification':
+    $ref: 'paths/actor-builds/actor-builds@{buildId}@openapi-specification.yaml'
   /v2/key-value-stores:
     $ref: paths/key-value-stores/key-value-stores.yaml
   '/v2/key-value-stores/{storeId}':

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

@@ -0,0 +1,31 @@
+get:
+  tags:
+    - Actor builds/Build 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.
+  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.'
+      required: true
+      style: simple
+      schema:
+        type: string
+        example: soSkq9ekdmfOslopH
+  responses:
+    '200':
+      description: ''
+      headers: {}
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/actor-builds/GetOpenApiResponse.yaml"

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

@@ -0,0 +1,41 @@
+get:
+  tags:
+    - Actors/Build 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.
+  operationId: act_openapiSpecification_get
+  security:
+    - apiKeyActorBuilds: []
+    - httpBearerActorBuilds: []
+  parameters:
+    - name: actorId
+      in: path
+      description: Actor ID or a tilde-separated owner's username and Actor name.
+      required: true
+      style: simple
+      schema:
+        type: string
+        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.'
+      required: true
+      style: simple
+      schema:
+        type: string
+        example: soSkq9ekdmfOslopH
+  responses:
+    '200':
+      description: ''
+      headers: {}
+      content:
+        application/json:
+          schema:
+            $ref: "../../components/schemas/actor-builds/GetOpenApiResponse.yaml"