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: advanced/rest-api/overview.mdx
+6-15Lines changed: 6 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,29 +4,23 @@ title: Overview
4
4
5
5
## Trigger Updates
6
6
7
-
Leverage the REST API to programmatically trigger an update when desired.
8
-
The primary use-case will be to trigger updates. We will be adding more and more
9
-
functionality to the API overtime. Let us know what else you want to see in
10
-
[our community](https://mintlify.com/community)!
7
+
Use our REST API to trigger updates programmatically. More API functionality is in development - share feature requests in [our community](https://mintlify.com/community).
11
8
12
9
## Authentication
13
10
14
-
You can generate an API key through
15
-
[the dashboard](https://dashboard.mintlify.com/settings/integrations). The API key is
16
-
associated with the entire org and can be used across multiple deployments.
11
+
Generate your API key in [the dashboard](https://dashboard.mintlify.com/settings/integrations). One API key works for all deployments in your org.
17
12
18
13
<Frame>
19
14
<imgsrc="/images/external-api-key.png" />
20
15
</Frame>
21
16
22
17
## Discovery API
23
18
24
-
The Discovery API allows you to embed an AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.
25
-
Responses include citations so you can point your users to the right places they need to get help.
19
+
The Discovery API lets you embed AI chat into any app. The chat is powered by your docs and provides cited responses to help users find information.
26
20
27
21
## Getting Started
28
22
29
-
To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
23
+
1. Generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
30
24
31
25
<Frame>
32
26
<img
@@ -36,10 +30,7 @@ To get started, you'll need to generate a Discovery API key in the [dashboard](h
36
30
</Frame>
37
31
38
32
<Note>
39
-
The Discovery API token is a public token that can be referenced in your
40
-
frontend code whereas the API key is a server-side token that should be kept
41
-
secret.
33
+
Discovery API tokens are public and safe for frontend code. API keys are for server-side use only and should remain private.
42
34
</Note>
43
35
44
-
Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use
45
-
the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
36
+
See our [example implementation](https://github.com/mintlify/discovery-api-example) or check out the live demo at [chat.mintlify.com](https://chat.mintlify.com).
description: 'Generate docs pages for your API endpoints using MDX'
3
+
description: 'Generate API docs using MDX'
4
4
---
5
5
6
-
Mintlify allows you to define your API endpoints using a combination of `mint.json`configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
6
+
Define your API endpoints using `mint.json`config, MDX metadata, and the `<ParamFields />` component to generate an API playground with request and response examples.
7
7
8
8
<Steps>
9
9
<Steptitle="Configure your API">
10
-
In your `mint.json` file, define your base URL and auth method:
10
+
Add API configuration to your `mint.json`:
11
11
12
12
```json
13
13
{
@@ -20,7 +20,7 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
20
20
}
21
21
```
22
22
23
-
If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
23
+
To hide the API playground:
24
24
25
25
```json
26
26
{
@@ -32,12 +32,11 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
32
32
}
33
33
```
34
34
35
-
Find a full list of API configurations [here](/settings/global#api-configurations).
35
+
See all API configurations [here](/settings/global#api-configurations).
36
36
</Step>
37
37
38
-
<Steptitle="Create your endpoint pages">
39
-
40
-
Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
38
+
<Steptitle="Create endpoint pages">
39
+
Create an MDX file for each endpoint with the required metadata:
41
40
42
41
```md
43
42
---
@@ -46,20 +45,18 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
46
45
---
47
46
```
48
47
49
-
You can specify path parameters by adding the parameter name to the path, wrapped with`{}`:
48
+
For path parameters, use`{}`:
50
49
51
50
```bash
52
51
https://api.example.com/v1/endpoint/{userId}
53
52
```
54
53
55
54
<Note>
56
-
57
-
If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
58
-
55
+
With `baseUrl` configured in mint.json, you can use relative paths like `/v1/endpoint`
59
56
</Note>
60
57
</Step>
61
58
62
-
<Steptitle="Add your endpoints to your docs">
63
-
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs[here](/settings/navigation).
59
+
<Steptitle="Add to navigation">
60
+
Add endpoint pages to your sidebar in `mint.json`'s `navigation` field. See [navigation docs](/settings/navigation).
Copy file name to clipboardExpand all lines: api-playground/openapi/setup.mdx
+30-93Lines changed: 30 additions & 93 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,16 +5,13 @@ 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
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+.
8
+
Add your OpenAPI document (JSON or YAML) following the [OpenAPI 3.0+ specification](https://swagger.io/specification/).
12
9
13
10
## Auto-populate API pages
14
11
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.
12
+
The quickest setup: Add an `openapi` field to your `mint.json` under a tab or anchor. Use either a file path or URL to your OpenAPI doc.
16
13
17
-
**Example with Anchors:**
14
+
**Using Anchors:**
18
15
19
16
```json {5}
20
17
{
@@ -29,9 +26,7 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta
29
26
}
30
27
```
31
28
32
-
33
-
34
-
**Example with Tabs:**
29
+
**Using Tabs:**
35
30
36
31
```json {6}
37
32
{
@@ -45,108 +40,50 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta
45
40
}
46
41
```
47
42
48
-
49
-
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.
43
+
<Tip>Validate your OpenAPI spec: `mintlify openapi-check <openapiFilenameOrUrl>`</Tip>
60
44
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.
45
+
Default page metadata will use:
46
+
-`title`: OpenAPI operation's `summary` or auto-generated from method/endpoint
47
+
-`description`: OpenAPI operation's `description`
48
+
-`version`: Anchor/tab's version value
62
49
63
-
## Create MDX files for API pages
50
+
## Custom API Pages
64
51
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). 
52
+
Need more control? Create MDX pages for your API operations.
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.
Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping).
89
-
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.
94
-
95
62
<Note>
96
-
If your OpenAPI document is invalid, the files will not autogenerate.
63
+
Invalid OpenAPI docs won't generate files.
97
64
</Note>
98
65
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.
102
-
103
-
<Snippetfile="api-playground/openapi.mdx" />
104
-
105
-
By using the OpenAPI reference, the name, description, parameters, responses,
106
-
and the API playground will be automatically generated from the OpenAPI document.
107
-
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.
110
-
111
-
<CodeGroup>
112
-
```md Example
113
-
---
114
-
title: "Get users"
115
-
openapi: "/path/to/openapi-1.json GET /users"
116
-
---
117
-
```
66
+
### Manual MDX Creation
118
67
119
-
```md Format
120
-
---
121
-
title: "title of the page"
122
-
openapi: openapi-file-path method path
123
-
---
124
-
```
125
-
</CodeGroup>
68
+
Create custom MDX pages by referencing OpenAPI operations in the frontmatter:
126
69
127
-
<br />
70
+
```md
71
+
---
72
+
title: "Get users"
73
+
openapi: "/path/to/openapi.json GET /users"
74
+
---
75
+
```
128
76
129
77
<Note>
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,
132
-
the page will be empty.
78
+
Method and path must exactly match your OpenAPI document.
133
79
</Note>
134
80
135
-
## Create MDX files for OpenAPI schemas
81
+
## OpenAPI Schema Pages
136
82
137
-
Mintlify also allows you to create individual pages for any OpenAPI schema
138
-
defined in an OpenAPI document's `components.schemas` field:
Copy file name to clipboardExpand all lines: code.mdx
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,15 +8,15 @@ icon: 'code'
8
8
9
9
### Inline Code
10
10
11
-
To denote a `word` or `phrase` as code, enclose it in backticks (`).
11
+
Use backticks (`) to mark `code` within text.
12
12
13
13
```
14
-
To denote a `word` or `phrase` as code, enclose it in backticks (`).
14
+
Use backticks (`) to mark `code` within text.
15
15
```
16
16
17
17
### Code Block
18
18
19
-
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
19
+
Create code blocks using three backticks. Add a language name for syntax highlighting, and optionally a filename.
20
20
21
21
```java HelloWorld.java
22
22
classHelloWorld {
@@ -36,4 +36,4 @@ class HelloWorld {
36
36
```
37
37
````
38
38
39
-
Visit the [Code Block page](/content/components/code) for more detailed docs.
39
+
For more details, see the [Code Block page](/content/components/code).
![mintlify[bot]](https://avatars.githubusercontent.com/in/222410?v=4&size=40){kind=avatar}
0 commit comments