diff --git a/sources/platform/actors/development/actor_definition/docker.md b/sources/platform/actors/development/actor_definition/docker.md index c4fa57ac5b..18f8c48156 100644 --- a/sources/platform/actors/development/actor_definition/docker.md +++ b/sources/platform/actors/development/actor_definition/docker.md @@ -2,7 +2,7 @@ title: Dockerfile description: Learn about Docker base images for Apify Actors and how to choose the right image based on your Actor's requirements and programming language. slug: /actors/development/actor-definition/dockerfile -sidebar_position: 7 +sidebar_position: 8 --- When developing an [Actor](/sources/platform/actors/index.mdx) on the Apify platform, you can choose from a variety of pre-built Docker images to serve as the base for your Actor. These base images come with pre-installed dependencies and tools, making it easier to set up your development environment and ensuring consistent behavior across different environments. diff --git a/sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md b/sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md index 53f3faf6a4..89ce713ff9 100644 --- a/sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md +++ b/sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md @@ -1,7 +1,7 @@ --- title: Dynamic Actor memory description: Automatically adjust your Actor memory allocation based on input size and run options to optimize performance and reduce costs on every run. -sidebar_position: 8 +sidebar_position: 9 slug: /actors/development/actor-definition/dynamic-actor-memory --- diff --git a/sources/platform/actors/development/actor_definition/images/console-standby-openapi-swagger.png b/sources/platform/actors/development/actor_definition/images/console-standby-openapi-swagger.png new file mode 100644 index 0000000000..403e8896da Binary files /dev/null and b/sources/platform/actors/development/actor_definition/images/console-standby-openapi-swagger.png differ diff --git a/sources/platform/actors/development/actor_definition/web_server_schema/index.md b/sources/platform/actors/development/actor_definition/web_server_schema/index.md new file mode 100644 index 0000000000..cf13896e1b --- /dev/null +++ b/sources/platform/actors/development/actor_definition/web_server_schema/index.md @@ -0,0 +1,108 @@ +--- +title: Web server schema +sidebar_label: Web server schema +sidebar_position: 7 +description: Attach an OpenAPI specification to your Actor to enable the interactive Standby tab in Apify Console and Apify Store, where you can browse and test endpoints. +slug: /actors/development/actor-definition/web-server-schema +--- + +The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. You can define the schema for any Actor that exposes an HTTP server. When you enable [standby mode](/platform/actors/development/programming-interface/standby), Apify Console and Apify Store render an interactive **Standby** tab on the Actor's detail page. From there you can browse endpoints, inspect request and response schemas, and send requests directly from the browser. + +![Apify Console showing the Standby tab with the Endpoints section rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png) + +## Define the web server schema + +You can define the OpenAPI spec inline in `.actor/actor.json` or reference a separate file. + +### Reference an external file + +```json title=".actor/actor.json" +{ + "actorSpecification": 1, + "name": "my-api-actor", + "version": "1.0", + "usesStandbyMode": true, + "webServerSchema": "./openapi.json" +} +``` + +Place your OpenAPI spec in `.actor/openapi.json`: + +```json title=".actor/openapi.json" +{ + "openapi": "3.0.0", + "info": { + "title": "My API Actor", + "version": "1.0.0" + }, + "paths": { + "/search": { + "get": { + "summary": "Search for items", + "parameters": [ + { + "name": "query", + "in": "query", + "required": true, + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Search results" + } + } + } + } + } +} +``` + +### Embed inline + +```json title=".actor/actor.json" +{ + "actorSpecification": 1, + "name": "my-api-actor", + "version": "1.0", + "usesStandbyMode": true, + "webServerSchema": { + "openapi": "3.0.0", + "info": { + "title": "My API Actor", + "version": "1.0.0" + }, + "paths": { + "/health": { + "get": { + "summary": "Health check", + "responses": { + "200": { "description": "OK" } + } + } + } + } + } +} +``` + +Follow the standard [OpenAPI 3.x format](https://spec.openapis.org/oas/latest.html) to describe your endpoints, parameters, request bodies, and responses. + +## Build and deploy + +The build process validates `webServerSchema`, similar to other Actor schemas like [input schema](/platform/actors/development/actor-definition/input-schema) and [dataset schema](/platform/actors/development/actor-definition/dataset-schema). If the spec is malformed, the build fails with a validation error. + +Once deployed, the **Standby** tab appears automatically on the Actor's detail page when you enable [standby mode](/platform/actors/development/programming-interface/standby). It renders your spec with [Swagger UI](https://swagger.io/tools/swagger-ui/) and handles authentication automatically - Actor users can send requests without configuring API tokens. + +:::note Servers field is overwritten + +Your `servers` array is replaced with the Actor's standby URL at display time. Custom server URLs are ignored. + +::: + +## Related fields + +| Field | Description | +| --- | --- | +| `usesStandbyMode` | Must be `true` for the **Standby** tab to appear. See [standby mode](/platform/actors/development/programming-interface/standby). | +| `webServerSchema` | The OpenAPI spec that powers the **Standby** tab. Defined in [`.actor/actor.json`](/platform/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. |