Skip to content

Commit 77ea5d6

Browse files
ethanpalmethanpalm
committed
update JSON examples
1 parent e32d8dd commit 77ea5d6

File tree

4 files changed

+99
-115
lines changed

4 files changed

+99
-115
lines changed

‎api-playground/migrating-from-mdx.mdx‎

Lines changed: 41 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -28,25 +28,23 @@ You can define metadata and content for each endpoint in your OpenAPI specificat
2828
Replace `MDX` page references with OpenAPI endpoints in your `docs.json`.
2929

3030
```json
31-
{
32-
"navigation": {
33-
"groups": [
34-
{
35-
"group": "API Reference",
36-
"openapi": "/path/to/openapi.json",
37-
"pages": [
38-
"overview",
39-
"authentication",
40-
"introduction",
41-
"GET /health",
42-
"quickstart",
43-
"POST /users",
44-
"GET /users/{id}",
45-
"advanced-features"
46-
]
47-
}
48-
]
49-
}
31+
"navigation": {
32+
"groups": [
33+
{
34+
"group": "API Reference",
35+
"openapi": "/path/to/openapi.json",
36+
"pages": [
37+
"overview",
38+
"authentication",
39+
"introduction",
40+
"GET /health",
41+
"quickstart",
42+
"POST /users",
43+
"GET /users/{id}",
44+
"advanced-features"
45+
]
46+
}
47+
]
5048
}
5149
```
5250

@@ -66,21 +64,19 @@ You can customize how your API documentation appears in your navigation.
6664
Combine automatically generated API pages with other pages:
6765

6866
```json
69-
{
70-
"navigation": {
71-
"groups": [
72-
{
73-
"group": "API Reference",
74-
"openapi": "openapi.json",
75-
"pages": [
76-
"api/overview",
77-
"GET /users",
78-
"POST /users",
79-
"api/authentication"
80-
]
81-
}
82-
]
83-
}
67+
"navigation": {
68+
"groups": [
69+
{
70+
"group": "API Reference",
71+
"openapi": "openapi.json",
72+
"pages": [
73+
"api/overview",
74+
"GET /users",
75+
"POST /users",
76+
"api/authentication"
77+
]
78+
}
79+
]
8480
}
8581
```
8682

@@ -89,19 +85,17 @@ Combine automatically generated API pages with other pages:
8985
Organize different API versions using tabs or groups:
9086

9187
```json
92-
{
93-
"navigation": {
94-
"tabs": [
95-
{
96-
"tab": "API v1",
97-
"openapi": "specs/v1.json"
98-
},
99-
{
100-
"tab": "API v2",
101-
"openapi": "specs/v2.json"
102-
}
103-
]
104-
}
88+
"navigation": {
89+
"tabs": [
90+
{
91+
"tab": "API v1",
92+
"openapi": "specs/v1.json"
93+
},
94+
{
95+
"tab": "API v2",
96+
"openapi": "specs/v2.json"
97+
}
98+
]
10599
}
106100
```
107101

‎api-playground/openapi-setup.mdx‎

Lines changed: 29 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -286,29 +286,27 @@ When you want more control over where endpoints appear in your documentation, yo
286286

287287
Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the `pages` field:
288288

289-
```json {13, 16-17}
290-
{
291-
"navigation": {
292-
"tabs": [
293-
{
294-
"tab": "Getting started",
295-
"pages": [
296-
"quickstart",
297-
"installation"
298-
]
299-
},
300-
{
301-
"tab": "API reference",
302-
"openapi": "/path/to/openapi.json",
303-
"pages": [
304-
"api-overview",
305-
"GET /users",
306-
"POST /users",
307-
"guides/authentication"
308-
]
309-
}
310-
]
311-
}
289+
```json {12, 15-16}
290+
"navigation": {
291+
"tabs": [
292+
{
293+
"tab": "Getting started",
294+
"pages": [
295+
"quickstart",
296+
"installation"
297+
]
298+
},
299+
{
300+
"tab": "API reference",
301+
"openapi": "/path/to/openapi.json",
302+
"pages": [
303+
"api-overview",
304+
"GET /users",
305+
"POST /users",
306+
"guides/authentication"
307+
]
308+
}
309+
]
312310
}
313311
```
314312

@@ -343,16 +341,14 @@ OpenAPI specifications are inherited down the navigation hierarchy. Child naviga
343341

344342
Reference specific endpoints without setting a default OpenAPI specification by including the file path:
345343

346-
```json {6-7}
347-
{
348-
"navigation": {
349-
"pages": [
350-
"introduction",
351-
"user-guides",
352-
"/path/to/openapi-v1.json POST /users",
353-
"/path/to/openapi-v2.json GET /orders"
354-
]
355-
}
344+
```json {5-6}
345+
"navigation": {
346+
"pages": [
347+
"introduction",
348+
"user-guides",
349+
"/path/to/openapi-v1.json POST /users",
350+
"/path/to/openapi-v2.json GET /orders"
351+
]
356352
}
357353
```
358354

‎api-playground/overview.mdx‎

Lines changed: 18 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -38,15 +38,13 @@ We recommend generating your API playground from an OpenAPI specification. See [
3838
This example generates a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation.
3939

4040
```json
41-
{
42-
"navigation": {
43-
"groups": [
44-
{
45-
"group": "API reference",
46-
"openapi": "openapi.json"
47-
}
48-
]
49-
}
41+
"navigation": {
42+
"groups": [
43+
{
44+
"group": "API reference",
45+
"openapi": "openapi.json"
46+
}
47+
]
5048
}
5149
```
5250

@@ -55,19 +53,17 @@ We recommend generating your API playground from an OpenAPI specification. See [
5553
This example generates pages for only the `GET /users` and `POST /users` endpoints. To genereate other endpoint pages, add additional endpoints to the `pages` array.
5654

5755
```json
58-
{
59-
"navigation": {
60-
"groups": [
61-
{
62-
"group": "API reference",
63-
"openapi": "openapi.json",
64-
"pages": [
65-
"GET /users",
66-
"POST /users"
67-
]
68-
}
69-
]
70-
}
56+
"navigation": {
57+
"groups": [
58+
{
59+
"group": "API reference",
60+
"openapi": "openapi.json",
61+
"pages": [
62+
"GET /users",
63+
"POST /users"
64+
]
65+
}
66+
]
7167
}
7268
```
7369

‎api-playground/troubleshooting.mdx‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -75,21 +75,19 @@ If your API pages aren't displaying correctly, check these common configuration
7575
If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues:
7676

7777
1. **Missing default OpenAPI spec**: Ensure you have an `openapi` field set for the navigation element:
78-
```json {6}
79-
{
80-
"navigation": {
81-
"groups": [
82-
{
83-
"group": "API reference",
84-
"openapi": "/path/to/openapi.json",
85-
"pages": [
86-
"GET /users",
87-
"POST /users"
88-
]
89-
}
78+
```json {5}
79+
"navigation": {
80+
"groups": [
81+
{
82+
"group": "API reference",
83+
"openapi": "/path/to/openapi.json",
84+
"pages": [
85+
"GET /users",
86+
"POST /users"
9087
]
9188
}
92-
}
89+
]
90+
}
9391
```
9492

9593
2. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.

0 commit comments

Comments
 (0)