diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 81eaca2ac..fc852c058 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -14,6 +14,8 @@ The API playground is an interactive environment that lets users test and explor The playground is automatically generated from your OpenAPI specification or AsyncAPI schema so any updates to your API are automatically reflected in the playground. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`. +The playground supports rich media responses including images, audio, and video content. When your API returns media content types, the playground automatically renders them inline for immediate preview. + We recommend generating your API playground from an OpenAPI specification. See [OpenAPI Setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document. ## Getting started @@ -142,6 +144,33 @@ Individual `MDX` pages are recommended for small APIs or when you want to experi For more information, see [x-mint extension](/api-playground/openapi-setup#x-mint-extension) and [MDX Setup](/api-playground/mdx/configuration). +## Media responses + +The API playground automatically detects and renders media content types in responses: + +- **Images** (`image/*`) - Display inline with full resolution +- **Audio** (`audio/*`) - Playable audio player with controls +- **Video** (`video/*`) - Embedded video player with controls + +When your API returns a response with a media content type, the playground renders it directly in the response panel. This allows users to immediately preview generated images, audio files, or video content without downloading. + +### Example + +If your API endpoint returns a video, ensure your OpenAPI specification includes the appropriate content type: + +```yaml +responses: + "200": + description: Generated video + content: + video/mp4: + schema: + type: string + format: binary +``` + +The playground will automatically render the video with playback controls when the endpoint is called. + ## Further reading - [AsyncAPI Setup](/api-playground/asyncapi/setup) for more information on creating your AsyncAPI schema to generate WebSocket reference pages.