You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: api-playground/openapi/setup.mdx
+38-15Lines changed: 38 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,19 +5,25 @@ description: "Reference OpenAPI endpoints in your docs pages"
5
5
6
6
## Add an OpenAPI specification file
7
7
8
-
To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI document in either JSON or YAML format that follows the [OpenAPI specification](https://swagger.io/specification/). Your document must follow OpenAPI specification 3.0+.
8
+
To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI
9
+
document in either JSON or YAML format that follows the
10
+
[OpenAPI specification](https://swagger.io/specification/). Your document must
11
+
follow OpenAPI specification 3.0+.
9
12
10
13
## Autogenerating the API playground
11
14
12
-
You can either [autogenerate the API playground](/settings/navigation#tabs) or create MDX files for the individual OpenAPI endpoints.
15
+
You can either [autogenerate the API playground](/settings/navigation#tabs) or
16
+
create MDX files for the individual OpenAPI endpoints.
13
17
14
18
### Auto-populate API pages
15
19
16
-
You can add an `openapi` field to an object in the `tabs` or `anchors` array in the `mint.json`. This can either be with OpenAPI documents that are in the docs repo (json or yaml) or hosted at a link.
20
+
You can add an `openapi` field to an object in the `tabs` or `anchors` array in
21
+
the `mint.json`. This can either be with OpenAPI documents that are in the docs
22
+
repo (json or yaml) or hosted at a link.
17
23
18
24
**Example with Anchors:**
19
25
20
-
```json
26
+
```json{5}
21
27
{
22
28
"anchors": [
23
29
{
@@ -34,7 +40,7 @@ You can add an `openapi` field to an object in the `tabs` or `anchors` array in
34
40
35
41
**Example with Tabs:**
36
42
37
-
```json
43
+
```json{6}
38
44
{
39
45
"tabs": [
40
46
{
@@ -50,30 +56,42 @@ You can add an `openapi` field to an object in the `tabs` or `anchors` array in
50
56
51
57
### Create MDX files for OpenAPI endpoints
52
58
53
-
You can also create MDX files associated with each OpenAPI endpoint if you would like to add additional context to specific pages or have more granular control over the navigation. Here is [the code](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech).
59
+
You can also create MDX files associated with each OpenAPI endpoint if you would
60
+
like to add additional context to specific pages or have more granular control
If you want to autogenerate MDX files for every endpoint in your OpenAPI document you can use our scraper.
67
+
If you want to autogenerate MDX files for every endpoint in your OpenAPI
68
+
document you can use our scraper.
58
69
59
70
#### Autogenerate files
60
71
61
-
Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the OpenAPI document in your codebase. If you're using a publicly-hosted OpenAPI document, you can supply the URL in place of a path.
The scraper will output an array of [Navigation entries](/settings/global#structure) containing your OpenAPI MDX files. You can either append these entries to your existing Navigation, or reorder and add the files to your navigation manually.
91
+
The scraper will output an array of
92
+
[Navigation entries](/settings/global#structure) containing your OpenAPI MDX
93
+
files. You can either append these entries to your existing Navigation, or
94
+
reorder and add the files to your navigation manually.
77
95
78
96
<Note>
79
97
If your OpenAPI document is invalid, the files will not autogenerate.
@@ -83,9 +101,13 @@ The scraper will output an array of [Navigation entries](/settings/global#struct
83
101
84
102
<Snippetfile="api-playground/openapi.mdx" />
85
103
86
-
By using the OpenAPI reference, the name, description, parameters, responses, and the API playground will be automatically generated using the specifications.
104
+
By using the OpenAPI reference, the name, description, parameters, responses,
105
+
and the API playground will be automatically generated using the specifications.
87
106
88
-
If you have multiple OpenAPI files, include the name of the OpenAPI file (without the file type `.json` or `.yaml`) to correctly map the information. This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file.
107
+
If you have multiple OpenAPI files, include the name of the OpenAPI file
108
+
(without the file type `.json` or `.yaml`) to correctly map the information.
109
+
This is not required if you have only one OpenAPI file - it will automatically
0 commit comments