Skip to content

Commit 2a7571d

Browse files
committed
edit page-level playground info
1 parent 02f29ab commit 2a7571d

File tree

2 files changed

+5
-46
lines changed

2 files changed

+5
-46
lines changed

api-playground/mdx/configuration.mdx

Lines changed: 4 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ To generate pages for API endpoints using `MDX`, configure your API settings in
5959

6060
</Note>
6161

62-
You can override the globally-defined display mode for the API playground per page by adding `playground` at the top of the `MDX` file:
62+
You can override the globally-defined display mode for the API playground for a page by adding `playground` to the frontmatter:
6363

6464
```mdx
6565
---
@@ -69,51 +69,10 @@ To generate pages for API endpoints using `MDX`, configure your API settings in
6969
---
7070
```
7171

72-
## Page-level playground control
72+
- `playground: 'interactive'` - Display the interactive playground.
73+
- `playground: 'simple'` - Display a copyable endpoint with no playground.
74+
- `playground: 'none'` - Hide the playground.
7375

74-
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.
75-
76-
### Available options
77-
78-
- `playground: 'interactive'` - Full interactive playground with request forms and response display
79-
- `playground: 'simple'` - Shows a copyable endpoint with no interactive elements
80-
- `playground: 'none'` - Completely hides the playground section
81-
82-
### Common use cases
83-
84-
**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:
85-
86-
```mdx
87-
---
88-
title: 'Order Status Webhook'
89-
api: 'POST https://api.yoursite.com/webhooks/order-status'
90-
playground: 'none'
91-
---
92-
93-
This webhook is triggered when an order status changes in our system.
94-
Configure your webhook endpoint to receive these notifications.
95-
```
96-
97-
**Internal or admin endpoints**: For endpoints that shouldn't be tested by regular users:
98-
99-
```mdx
100-
---
101-
title: 'Admin User Management'
102-
api: 'DELETE https://api.yoursite.com/admin/users/{id}'
103-
playground: 'simple'
104-
---
105-
```
106-
107-
**Documentation-heavy endpoints**: When you want to emphasize written documentation over interactive testing:
108-
109-
```mdx
110-
---
111-
title: 'Complex Analytics Query'
112-
api: 'POST https://api.yoursite.com/analytics/query'
113-
playground: 'simple'
114-
---
115-
```
116-
11776
</Step>
11877

11978
<Step title="Add your endpoints to your docs">

api-playground/overview.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ When you need more control over your API documentation, create individual `MDX`
112112
- Add additional content like examples
113113
- Hide specific operations
114114
- Reorder pages in your navigation
115-
- Control playground behavior per page (useful for webhooks and admin endpoints)
115+
- Control playground behavior per page
116116

117117
See [MDX Setup](/api-playground/mdx/configuration) for more information on creating individual pages for your API endpoints.
118118

0 commit comments

Comments
 (0)