diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml index e4e109f8eb..777f21b3f9 100644 --- a/fern/products/api-def/api-def.yml +++ b/fern/products/api-def/api-def.yml @@ -136,7 +136,9 @@ navigation: - page: Ignoring elements path: ./asyncapi/extensions/ignore.mdx - page: Server names - path: ./asyncapi/extensions/server-name.mdx + path: ./asyncapi/extensions/server-name.mdx + - page: API Explorer control + path: ./asyncapi/extensions/explorer.mdx - section: OpenRPC collapsed: true slug: openrpc diff --git a/fern/products/api-def/asyncapi/extensions/explorer.mdx b/fern/products/api-def/asyncapi/extensions/explorer.mdx new file mode 100644 index 0000000000..68a0766fb5 --- /dev/null +++ b/fern/products/api-def/asyncapi/extensions/explorer.mdx @@ -0,0 +1,53 @@ +--- +title: API Explorer control +headline: API Explorer control (AsyncAPI) +description: Enable or disable the API Explorer for WebSocket channels using `x-fern-explorer` +--- + + +The [API Explorer](/learn/docs/api-references/api-explorer) is enabled by default for every WebSocket channel. Set `x-fern-explorer: false` at the document root to hide the Playground for all channels, and override it on individual channels; a channel's own value takes precedence. Non-boolean values are reported as errors when importing the specification. + + + + ```yaml title="asyncapi.yml" {5,9} + asyncapi: 3.0.0 + info: + title: Plant Store API + version: 1.0.0 + x-fern-explorer: false # Disable the Explorer for all channels + channels: + plantMonitor: + address: /plants/monitor + x-fern-explorer: true # Enable the Explorer for this channel + messages: + moistureReading: + $ref: "#/components/messages/MoistureReading" + plantUpdates: + address: /plants/updates # Remains disabled (document-level value applies) + messages: + statusUpdate: + $ref: "#/components/messages/StatusUpdate" + ``` + + + ```yaml title="asyncapi.yml" {5,8} + asyncapi: 2.6.0 + info: + title: Plant Store API + version: 1.0.0 + x-fern-explorer: false # Disable the Explorer for all channels + channels: + /plants/monitor: + x-fern-explorer: true # Enable the Explorer for this channel + subscribe: + operationId: monitorPlants + message: + $ref: "#/components/messages/MoistureReading" + /plants/updates: # Remains disabled (document-level value applies) + subscribe: + operationId: plantUpdates + message: + $ref: "#/components/messages/StatusUpdate" + ``` + + diff --git a/fern/products/api-def/asyncapi/extensions/overview.md b/fern/products/api-def/asyncapi/extensions/overview.md index 8b72da0350..b9ae598656 100644 --- a/fern/products/api-def/asyncapi/extensions/overview.md +++ b/fern/products/api-def/asyncapi/extensions/overview.md @@ -20,6 +20,7 @@ The table below shows all available extensions and links to detailed documentati | [`x-fern-availability`](./availability) | Mark features as available in specific SDK versions | | [`x-fern-audiences`](./audiences) | Filter operations by audience | | [`x-fern-sdk-method-name`](./method-names) | Customize SDK method names | +| [`x-fern-explorer`](./api-explorer-control) | Control API Explorer (playground) availability globally or per channel | If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it. diff --git a/fern/products/api-def/openapi/extensions/explorer.mdx b/fern/products/api-def/openapi/extensions/explorer.mdx index 1406a8d72b..aa2c249b67 100644 --- a/fern/products/api-def/openapi/extensions/explorer.mdx +++ b/fern/products/api-def/openapi/extensions/explorer.mdx @@ -5,7 +5,7 @@ description: Enable or disable the API Explorer using `x-fern-explorer` --- -The [API Explorer](/learn/docs/api-references/api-explorer) is enabled by default for all endpoints. Use `x-fern-explorer` to disable or it globally or to override it per operation. This is commonly used to disable the Explorer for destructive operations, payment processing, or admin-only endpoints. +The [API Explorer](/learn/docs/api-references/api-explorer) is enabled by default for all endpoints. Use `x-fern-explorer` to disable it globally or to override it per operation. This is commonly used to disable the Explorer for destructive operations, payment processing, or admin-only endpoints. AsyncAPI specs support the same extension [per WebSocket channel](/learn/api-definitions/asyncapi/extensions/api-explorer-control). ## Global diff --git a/fern/products/docs/pages/api-references/api-explorer.mdx b/fern/products/docs/pages/api-references/api-explorer.mdx index 4ede707e94..86c5c3411a 100644 --- a/fern/products/docs/pages/api-references/api-explorer.mdx +++ b/fern/products/docs/pages/api-references/api-explorer.mdx @@ -55,7 +55,7 @@ For APIs that support WebSocket connections, the API Explorer includes a **WebSo ## Disable the API Explorer -For OpenAPI specs, the API Explorer is enabled by default for all endpoints. To turn it off globally or per endpoint, use the [`x-fern-explorer`](/learn/api-definitions/openapi/extensions/api-explorer-control) extension. This is commonly used to disable the Explorer for destructive operations, payment processing, or admin-only endpoints. +For OpenAPI specs, the API Explorer is enabled by default for all endpoints. To turn it off globally or per endpoint, use the [`x-fern-explorer`](/learn/api-definitions/openapi/extensions/api-explorer-control) extension. This is commonly used to disable the Explorer for destructive operations, payment processing, or admin-only endpoints. For AsyncAPI specs, the same extension applies [per channel](/learn/api-definitions/asyncapi/extensions/api-explorer-control). Setting [`disable-explorer-proxy`](/learn/docs/configuration/site-level-settings#settingsdisable-explorer-proxy) does not turn the Explorer off. It keeps the Explorer running and routes requests directly to your API instead of through Fern's proxy. diff --git a/fern/products/docs/pages/changelog/2026-08-19.mdx b/fern/products/docs/pages/changelog/2026-08-19.mdx new file mode 100644 index 0000000000..03f376dab3 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-08-19.mdx @@ -0,0 +1,7 @@ +## Disable the API Explorer for WebSocket channels + +api-reference + +You can now turn off the API Explorer for WebSocket channels defined in an AsyncAPI specification. Set `x-fern-explorer: false` at the document root to hide the Playground for every channel, and override it on individual channels with `x-fern-explorer: true`. + +