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
+72-52Lines changed: 72 additions & 52 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,19 +5,18 @@ 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
-
## Autogenerating the API playground
13
+
## Auto-populate API pages
11
14
12
-
You can either [autogenerate the API playground](/settings/navigation#tabs) or create MDX files for the individual OpenAPI endpoints.
13
-
14
-
### Auto-populate API pages
15
-
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.
15
+
The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor.
17
16
18
17
**Example with Anchors:**
19
18
20
-
```json
19
+
```json{5}
21
20
{
22
21
"anchors": [
23
22
{
@@ -34,7 +33,7 @@ You can add an `openapi` field to an object in the `tabs` or `anchors` array in
34
33
35
34
**Example with Tabs:**
36
35
37
-
```json
36
+
```json{6}
38
37
{
39
38
"tabs": [
40
39
{
@@ -48,85 +47,106 @@ You can add an `openapi` field to an object in the `tabs` or `anchors` array in
48
47
49
48
50
49
51
-
### Create MDX files for OpenAPI endpoints
50
+
<Tip>To validate your OpenAPI spec, you can use this command: <br/>`mintlify openapi-check <openapiFilenameOrUrl>`</Tip>
51
+
52
+
53
+
When using this option, the metadata for the generated pages will have the following default values:
54
+
55
+
*`title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
56
+
57
+
*`description`: The `description` field from the OpenAPI operation, if present.
58
+
59
+
*`version`: The `version` value from the anchor or tab, if present.
60
+
61
+
There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.
52
62
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).
63
+
## Create MDX files for API pages
64
+
65
+
If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](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). 
If you want to autogenerate MDX files for every endpoint in your OpenAPI document you can use our scraper.
69
+
### Autogenerate files
58
70
59
-
#### Autogenerate files
71
+
For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.
60
72
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.
Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping).
75
89
76
-
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.
90
+
The scraper will output an array of
91
+
[Navigation entries](/settings/global#structure) containing your OpenAPI MDX
92
+
files. You can either append these entries to your existing Navigation, or
93
+
reorder and add the files to your navigation manually.
77
94
78
95
<Note>
79
96
If your OpenAPI document is invalid, the files will not autogenerate.
80
97
</Note>
81
98
82
-
#### Manually specify files
99
+
### Manually specify files
100
+
101
+
You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.
83
102
84
103
<Snippetfile="api-playground/openapi.mdx" />
85
104
86
-
By using the OpenAPI reference, the name, description, parameters, responses, and the API playground will be automatically generated using the specifications.
105
+
By using the OpenAPI reference, the name, description, parameters, responses,
106
+
and the API playground will be automatically generated from the OpenAPI document.
87
107
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.
108
+
If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have
109
+
only one OpenAPI file - it will automatically detect your OpenAPI file.
89
110
90
111
<CodeGroup>
91
-
92
-
```md Example
93
-
---
94
-
title: "Get users"
95
-
openapi: "openapi-1 GET /users"
96
-
---
97
-
```
98
-
99
-
```md Format
100
-
---
101
-
title: "title of the page"
102
-
openapi: openapi-file-name method endpoint
103
-
---
104
-
```
105
-
112
+
```md Example
113
+
---
114
+
title: "Get users"
115
+
openapi: "/path/to/openapi-1.json GET /users"
116
+
---
117
+
```
118
+
119
+
```md Format
120
+
---
121
+
title: "title of the page"
122
+
openapi: openapi-file-path method path
123
+
---
124
+
```
106
125
</CodeGroup>
126
+
107
127
<br />
128
+
108
129
<Note>
109
-
The method endpoint must match the endpoint specified in the OpenAPI
110
-
specifications exactly. If the endpoint doesn't exist in the OpenAPI file,
130
+
The method and path must match the method and path specified in the OpenAPI
131
+
document exactly. If the endpoint doesn't exist in the OpenAPI file,
111
132
the page will be empty.
112
133
</Note>
113
134
114
135
## Create MDX files for OpenAPI schemas
115
136
116
-
Mintlify also allows you to create individual pages for any OpenAPI schema defined in an OpenAPI document's `components.schemas` field:
137
+
Mintlify also allows you to create individual pages for any OpenAPI schema
138
+
defined in an OpenAPI document's `components.schemas` field:
0 commit comments