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 index cf13896e1b..ecf6e7c241 100644 --- a/sources/platform/actors/development/actor_definition/web_server_schema/index.md +++ b/sources/platform/actors/development/actor_definition/web_server_schema/index.md @@ -6,7 +6,7 @@ description: Attach an OpenAPI specification to your Actor to enable the interac 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. +The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. OpenAPI 3.1 documents are not accepted by the build validator - see [OpenAPI 3.0 compatibility](/platform/actors/development/actor-definition/web-server-schema/openapi-version) for the 3.1 constructs that break the build and how to rewrite them. 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) @@ -86,7 +86,7 @@ Place your OpenAPI spec in `.actor/openapi.json`: } ``` -Follow the standard [OpenAPI 3.x format](https://spec.openapis.org/oas/latest.html) to describe your endpoints, parameters, request bodies, and responses. +Follow the [OpenAPI 3.0.x format](https://spec.openapis.org/oas/v3.0.3) to describe your endpoints, parameters, request bodies, and responses. If you have an OpenAPI 3.1 document, see [OpenAPI 3.0 compatibility](/platform/actors/development/actor-definition/web-server-schema/openapi-version) for the translations you need to apply. ## Build and deploy diff --git a/sources/platform/actors/development/actor_definition/web_server_schema/openapi_version.md b/sources/platform/actors/development/actor_definition/web_server_schema/openapi_version.md new file mode 100644 index 0000000000..ef705e37bd --- /dev/null +++ b/sources/platform/actors/development/actor_definition/web_server_schema/openapi_version.md @@ -0,0 +1,138 @@ +--- +title: OpenAPI 3.0 compatibility +sidebar_label: OpenAPI 3.0 compatibility +sidebar_position: 1 +description: The webServerSchema field expects an OpenAPI 3.0.x document. This page lists common OpenAPI 3.1 constructs that break the build and shows the 3.0.x form to use instead. +slug: /actors/development/actor-definition/web-server-schema/openapi-version +--- + +`webServerSchema` in `.actor/actor.json` accepts an [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.3) document. The build validator does not accept OpenAPI 3.1 constructs, and specs that rely on 3.1-only syntax fail the build with a validation error. + +If you are copying an existing spec or generating one with a tool that defaults to 3.1, downgrade it before adding it to your Actor. + +## Set the version string + +Use `"openapi": "3.0.3"` (or any `3.0.x`) at the top of the document. Do not use `"openapi": "3.1.0"`. + +```json +{ + "openapi": "3.0.3", + "info": { "title": "My API Actor", "version": "1.0.0" }, + "paths": { } +} +``` + +## Nullable properties + +In OpenAPI 3.1 a nullable property is expressed with a type array that includes `"null"`. In 3.0 you must use the `nullable: true` keyword alongside a single `type`. + +Do not use the 3.1 form: + +```json +{ + "type": ["string", "null"] +} +``` + +Use the 3.0 form: + +```json +{ + "type": "string", + "nullable": true +} +``` + +The same rule applies to any property, request body field, response body field, or reusable schema under `components.schemas`. + +## Common 3.1 to 3.0 translations + +| Concept | OpenAPI 3.1 | OpenAPI 3.0.x (use this) | +| --- | --- | --- | +| Nullable value | `"type": ["string", "null"]` | `"type": "string", "nullable": true` | +| Exclusive minimum | `"exclusiveMinimum": 0` | `"minimum": 0, "exclusiveMinimum": true` | +| Exclusive maximum | `"exclusiveMaximum": 100` | `"maximum": 100, "exclusiveMaximum": true` | +| Constant value | `"const": "foo"` | `"enum": ["foo"]` | +| Multiple examples on a schema | `"examples": [1, 2, 3]` | `"example": 1` (single example only) | +| No request body content | Omit `requestBody` or use `"content": {}` | Omit `requestBody`; do not use an empty `content` object | +| JSON Schema draft override | `"$schema": "..."` inside a schema | Not allowed; remove the keyword | +| Webhooks | Top-level `webhooks` object | Not supported; document webhooks in the README instead | +| File uploads | `"contentMediaType": "image/png"` on a `string` | `"type": "string", "format": "binary"` | + +## Full nullable example + +```json title=".actor/openapi.json" +{ + "openapi": "3.0.3", + "info": { + "title": "My API Actor", + "version": "1.0.0" + }, + "paths": { + "/items/{id}": { + "get": { + "summary": "Fetch an item", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "The item, or a null body if it is a placeholder", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Item" } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Item": { + "type": "object", + "required": ["id", "name"], + "properties": { + "id": { "type": "string" }, + "name": { "type": "string" }, + "description": { + "type": "string", + "nullable": true + }, + "price": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": true + }, + "status": { + "type": "string", + "enum": ["active"] + } + } + } + } + } +} +``` + +## Validating locally + +Before pushing your Actor you can validate the spec against 3.0.x with any standard OpenAPI tool, for example: + +```bash +npx @redocly/cli lint .actor/openapi.json +``` + +or + +```bash +npx @apidevtools/swagger-cli validate .actor/openapi.json +``` + +If the tool reports 3.1-only constructs (`type` array with `null`, top-level `webhooks`, `const`, and so on), rewrite them using the table above before running `apify push`.