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
+61-41Lines changed: 61 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,15 +8,19 @@ description: "Reference OpenAPI endpoints in your docs pages"
8
8
To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI
9
9
document in either JSON or YAML format that follows the
10
10
[OpenAPI specification](https://swagger.io/specification/). Your document must
11
-
follow OpenAPI specification 3.0+.
12
-
<Tip>To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mint) and run this command: <br/>`mint openapi-check <openapiFilenameOrUrl>`</Tip>
11
+
follow OpenAPI specification 3.0\+.
12
+
<Tip>
13
+
To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mint) and run this command: \
14
+
`mint openapi-check <openapiFilenameOrUrl>`
15
+
</Tip>
16
+
13
17
14
18
## Auto-populate API pages
15
19
16
20
The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.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.
17
21
18
-
19
22
**Example with Tabs:**
23
+
20
24
```json {5}
21
25
"navigation": {
22
26
"tabs": [
@@ -27,9 +31,13 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta
27
31
]
28
32
}
29
33
```
30
-
34
+
35
+
<Note>
36
+
The above example is with tabs but you can add an `openapi` property to any [navigation division](/navigation)
37
+
</Note>
31
38
32
39
**Example with Groups:**
40
+
33
41
```json {8-11}
34
42
"navigation": {
35
43
"tabs": [
@@ -49,23 +57,26 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta
49
57
}
50
58
```
51
59
52
-
<Note>The directory field is optional. If not specified, the files will be placed in the **api-reference** folder of the docs repo.</Note>
60
+
<Note>
61
+
The directory field is optional. If not specified, the files will be placed in the **api-reference** folder of the docs repo.
62
+
</Note>
53
63
54
64
When using this option, the metadata for the generated pages will have the following default values:
55
65
56
-
*`title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
57
-
58
-
*`description`: The `description` field from the OpenAPI operation, if present.
59
-
60
-
*`version`: The `version` value from the anchor or tab, if present.
66
+
-`title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
67
+
-`description`: The `description` field from the OpenAPI operation, if present.
68
+
-`version`: The `version` value from the anchor or tab, if present.
69
+
-`deprecated`: The `deprecated` field from the OpenAPI operation, if present. If true, a deprecated label will appear next to the endpoint in the side navigation and next to the title of the endpoint page.
61
70
62
71
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.
63
72
64
-
<Tip>If you have some endpoints in your OpenAPI schema that you don't want pages generated for automatically, you can add the [x-hidden](/api-playground/openapi/advanced-features#x-hidden) property</Tip>
73
+
<Tip>
74
+
If you have some endpoints in your OpenAPI schema that you don't want pages generated for automatically, you can add the [x-hidden](/api-playground/openapi/advanced-features#x-hidden) property
75
+
</Tip>
65
76
66
77
## Create MDX files for API pages
67
78
68
-
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/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases). 
79
+
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/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases).
69
80
70
81
71
82
@@ -84,19 +95,28 @@ only one OpenAPI file - it will automatically detect your OpenAPI file.
84
95
If you want to reference an external OpenAPI file using this method, provide the file’s URL in the docs.json. See [here](https://mintlify.com/docssettings#param-source-4) for the correct format.
85
96
86
97
<CodeGroup>
87
-
```md Example
88
-
---
89
-
title: "Get users"
90
-
openapi: "/path/to/openapi-1.json GET /users"
91
-
---
92
-
```
93
-
94
-
```md Format
95
-
---
96
-
title: "title of the page"
97
-
openapi: openapi-file-path method path
98
-
---
99
-
```
98
+
99
+
```md Example
100
+
---
101
+
title: "Get users"
102
+
description: "Returns all plants from the system that the user has access to"
Copy file name to clipboardExpand all lines: components/columns.mdx
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,28 +4,28 @@ description: 'Show cards side by side in a grid format'
4
4
icon: 'columns-2'
5
5
---
6
6
7
-
The `CardGroup` component lets you group multiple `Card` components together. It's most often used to put multiple cards in a grid, by specifying the number of grid columns.
7
+
The `Columns` component lets you group multiple `Card` components together. It's most often used to put multiple cards in a grid, by specifying the number of grid columns.
8
8
9
-
<CardGroupcols={2}>
9
+
<Columnscols={2}>
10
10
<Cardtitle="First Card"icon="panel-left-close">
11
11
Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
12
12
</Card>
13
13
<Cardtitle="Second Card"icon="panel-right-close">
14
14
Lorem ipsum dolor sit amet, consectetur adipiscing elit
15
15
</Card>
16
-
</CardGroup>
16
+
</Columns>
17
17
18
18
<RequestExample>
19
19
20
20
```jsx Card Group Example
21
-
<CardGroup cols={2}>
21
+
<Columns cols={2}>
22
22
<Card title="First Card">
23
23
Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
24
24
</Card>
25
25
<Card title="Second Card">
26
26
Lorem ipsum dolor sit amet, consectetur adipiscing elit
description: 'Specify the content of the right side panel'
4
+
icon: 'panel-right'
5
+
---
6
+
7
+
You can use the `<Panel>` component to customize the right side panel of a page with any components that you want.
8
+
9
+
If a page has a `<Panel>` component, any [RequestExample](/components/examples#request-example) and [ResponseExample](/components/examples#response-example) components must be inside `<Panel>`.
10
+
11
+
The components in a `<Panel>` will replace a page's table of contents.
12
+
13
+
````md
14
+
<Panel>
15
+
<Info>Pin info to the side panel. Or add any other component.</Info>
16
+
</Panel>
17
+
````
18
+
19
+
<Panel>
20
+
<Info>Pin info to the side panel. Or add any other component.</Info>
0 commit comments