From 02f29abcc917bdac9e6fba59fb537af10f2c4e73 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 12:04:35 -0700 Subject: [PATCH 1/2] Claude Code's commit --- api-playground/mdx/configuration.mdx | 45 ++++++++++++++++++++++++++++ api-playground/overview.mdx | 1 + 2 files changed, 46 insertions(+) diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 1bc9a9da2..74367a0d0 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -68,6 +68,51 @@ To generate pages for API endpoints using `MDX`, configure your API settings in playground: 'none' --- ``` + + ## Page-level playground control + + The `playground` frontmatter property allows you to control the API playground functionality on individual pages, overriding any global settings defined in `docs.json`. This is particularly useful for endpoints that don't benefit from interactive testing. + + ### Available options + + - `playground: 'interactive'` - Full interactive playground with request forms and response display + - `playground: 'simple'` - Shows a copyable endpoint with no interactive elements + - `playground: 'none'` - Completely hides the playground section + + ### Common use cases + + **Webhook endpoints**: Since webhooks are triggered by external systems rather than user requests, an interactive playground isn't useful. Use `playground: 'none'` to focus on documentation: + + ```mdx + --- + title: 'Order Status Webhook' + api: 'POST https://api.yoursite.com/webhooks/order-status' + playground: 'none' + --- + + This webhook is triggered when an order status changes in our system. + Configure your webhook endpoint to receive these notifications. + ``` + + **Internal or admin endpoints**: For endpoints that shouldn't be tested by regular users: + + ```mdx + --- + title: 'Admin User Management' + api: 'DELETE https://api.yoursite.com/admin/users/{id}' + playground: 'simple' + --- + ``` + + **Documentation-heavy endpoints**: When you want to emphasize written documentation over interactive testing: + + ```mdx + --- + title: 'Complex Analytics Query' + api: 'POST https://api.yoursite.com/analytics/query' + playground: 'simple' + --- + ``` diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index d3c6e36b2..1af098bec 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -112,6 +112,7 @@ When you need more control over your API documentation, create individual `MDX` - Add additional content like examples - Hide specific operations - Reorder pages in your navigation +- Control playground behavior per page (useful for webhooks and admin endpoints) See [MDX Setup](/api-playground/mdx/configuration) for more information on creating individual pages for your API endpoints. From 2a7571db4cd602628cbb5b008d87c4bdefe28b3a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 8 Jul 2025 12:19:29 -0700 Subject: [PATCH 2/2] edit page-level playground info --- api-playground/mdx/configuration.mdx | 49 +++------------------------- api-playground/overview.mdx | 2 +- 2 files changed, 5 insertions(+), 46 deletions(-) diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index 74367a0d0..4d989cdc3 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -59,7 +59,7 @@ To generate pages for API endpoints using `MDX`, configure your API settings in - You can override the globally-defined display mode for the API playground per page by adding `playground` at the top of the `MDX` file: + You can override the globally-defined display mode for the API playground for a page by adding `playground` to the frontmatter: ```mdx --- @@ -69,51 +69,10 @@ To generate pages for API endpoints using `MDX`, configure your API settings in --- ``` - ## Page-level playground control + - `playground: 'interactive'` - Display the interactive playground. + - `playground: 'simple'` - Display a copyable endpoint with no playground. + - `playground: 'none'` - Hide the playground. - The `playground` frontmatter property allows you to control the API playground functionality on individual pages, overriding any global settings defined in `docs.json`. This is particularly useful for endpoints that don't benefit from interactive testing. - - ### Available options - - - `playground: 'interactive'` - Full interactive playground with request forms and response display - - `playground: 'simple'` - Shows a copyable endpoint with no interactive elements - - `playground: 'none'` - Completely hides the playground section - - ### Common use cases - - **Webhook endpoints**: Since webhooks are triggered by external systems rather than user requests, an interactive playground isn't useful. Use `playground: 'none'` to focus on documentation: - - ```mdx - --- - title: 'Order Status Webhook' - api: 'POST https://api.yoursite.com/webhooks/order-status' - playground: 'none' - --- - - This webhook is triggered when an order status changes in our system. - Configure your webhook endpoint to receive these notifications. - ``` - - **Internal or admin endpoints**: For endpoints that shouldn't be tested by regular users: - - ```mdx - --- - title: 'Admin User Management' - api: 'DELETE https://api.yoursite.com/admin/users/{id}' - playground: 'simple' - --- - ``` - - **Documentation-heavy endpoints**: When you want to emphasize written documentation over interactive testing: - - ```mdx - --- - title: 'Complex Analytics Query' - api: 'POST https://api.yoursite.com/analytics/query' - playground: 'simple' - --- - ``` - diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 1af098bec..1fc8aca58 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -112,7 +112,7 @@ When you need more control over your API documentation, create individual `MDX` - Add additional content like examples - Hide specific operations - Reorder pages in your navigation -- Control playground behavior per page (useful for webhooks and admin endpoints) +- Control playground behavior per page See [MDX Setup](/api-playground/mdx/configuration) for more information on creating individual pages for your API endpoints.