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
description: "Reference OpenAPI endpoints in your docs pages"
4
4
---
5
5
6
-
## Add an OpenAPI specification file
6
+
## Getting Started with OpenAPI Integration
7
7
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+.
12
-
<Tip>To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mintlify) and run this command: <br/>`mintlify openapi-check <openapiFilenameOrUrl>`</Tip>
8
+
### Prerequisites
9
+
Before integrating OpenAPI into your documentation, ensure you have:
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.
15
+
<Tip>
16
+
Validate your OpenAPI specification using our CLI:
17
+
```bash
18
+
mintlify openapi-check <openapiFilenameOrUrl>
19
+
```
20
+
</Tip>
21
+
22
+
## Implementation Methods
23
+
24
+
### Method 1: Auto-population with Navigation Tabs
17
25
26
+
The quickest way to implement OpenAPI is through your `docs.json` configuration. You can either reference a local file or a hosted URL.
When using this option, the metadata for the generated pages will have the following default values:
53
-
54
-
*`title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
55
-
56
-
*`description`: The `description` field from the OpenAPI operation, if present.
57
-
58
-
*`version`: The `version` value from the anchor or tab, if present.
59
-
60
-
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.
61
-
62
-
## Create MDX files for API pages
63
-
64
-
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). 
65
-
66
-
67
-
68
-
### Manually specify files
69
-
70
-
You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.
71
-
72
-
<Snippetfile="api-playground/openapi.mdx" />
73
-
74
-
By using the OpenAPI reference, the name, description, parameters, responses,
75
-
and the API playground will be automatically generated from the OpenAPI document.
76
-
77
-
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
78
-
only one OpenAPI file - it will automatically detect your OpenAPI file.
79
-
80
-
<CodeGroup>
81
-
```md Example
82
-
---
83
-
title: "Get users"
84
-
openapi: "/path/to/openapi-1.json GET /users"
85
-
---
86
-
```
87
-
88
-
```md Format
89
-
---
90
-
title: "title of the page"
91
-
openapi: openapi-file-path method path
92
-
---
93
-
```
94
62
</CodeGroup>
95
63
96
-
<br />
64
+
<Info>
65
+
Auto-generated pages will use the following metadata by default:
66
+
-**Title**: OpenAPI operation summary or generated from HTTP method/endpoint
67
+
-**Description**: OpenAPI operation description
68
+
-**Version**: Version value from the anchor/tab (if present)
69
+
</Info>
70
+
71
+
### Method 2: Custom MDX Pages
72
+
73
+
For more control over your API documentation, you can create individual MDX pages for each operation.
74
+
75
+
<Steps>
76
+
<Steptitle="Create an MDX File">
77
+
Create a new MDX file for your API endpoint. Here's an example structure:
78
+
```md
79
+
---
80
+
title: "Get users"
81
+
openapi: "/path/to/openapi-1.json GET /users"
82
+
---
83
+
```
84
+
</Step>
85
+
86
+
<Steptitle="Specify OpenAPI Reference">
87
+
The `openapi` field format should follow:
88
+
```
89
+
openapi: <file-path> <method> <path>
90
+
```
91
+
92
+
<Note>
93
+
If you only have one OpenAPI file, the file path is optional - Mintlify will automatically detect it.
94
+
</Note>
95
+
</Step>
96
+
97
+
<Steptitle="Add Custom Content">
98
+
Add any additional content or customization below the frontmatter.
99
+
</Step>
100
+
</Steps>
101
+
102
+
<Warning>
103
+
The method and path must exactly match those in your OpenAPI document. For webhooks, use "webhook" instead of the HTTP method (e.g., "POST").
104
+
</Warning>
105
+
106
+
### Method 3: Automated File Generation
107
+
108
+
For large OpenAPI documents, use our scraping tool to automatically generate MDX files.
109
+
110
+
<Steps>
111
+
<Steptitle="Install the Scraper">
112
+
Use our [@mintlify/scraping](https://www.npmjs.com/package/@mintlify/scraping) package:
Add the generated navigation entries to your configuration:
127
+
- Append them to existing navigation, or
128
+
- Manually organize them in your preferred structure
129
+
</Step>
130
+
</Steps>
97
131
98
132
<Note>
99
-
In most cases, the method and path must match the method and path specified
100
-
in the OpenAPI document exactly. If the endpoint doesn't exist in the OpenAPI
101
-
file, the page will be empty.
102
-
103
-
For webhooks, replace the method (i.e. "POST") with "webhook" (case insensitive)
104
-
and the correct method will be generated.
133
+
The scraper requires a valid OpenAPI document. Invalid specifications will not generate files.
105
134
</Note>
106
135
107
-
### Autogenerate files
108
-
109
-
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.
![mintlify[bot]](https://avatars.githubusercontent.com/in/222410?v=4&size=40){kind=avatar}
0 commit comments