Skip to content

Commit 0115c03

Browse files
mintlify-development[bot]mintlify-development[bot]
authored
Documentation edits made through Mintlify web editor
1 parent 9f9e9aa commit 0115c03

File tree

7 files changed

+642
-1054
lines changed

7 files changed

+642
-1054
lines changed

‎api-playground/openapi/setup.mdx‎

Lines changed: 70 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -3,35 +3,47 @@ title: "OpenAPI Setup"
33
description: "Reference OpenAPI endpoints in your docs pages"
44
---
55

6-
## Add an OpenAPI specification file
6+
## Adding Your OpenAPI Spec
77

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+
### Format Requirements
9+
Make sure your OpenAPI document follows these requirements:
10+
- Valid JSON or YAML format
11+
- Follows OpenAPI specification 3.0+
12+
- Contains complete endpoint and schema definitions
1213

13-
## Auto-populate API pages
14+
### Validating Your Spec
15+
Before proceeding, validate your OpenAPI spec using our CLI tool:
1416

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+
```bash
18+
mintlify openapi-check <openapiFilenameOrUrl>
19+
```
20+
21+
## Auto-Generation Options
1622

17-
**Example with Anchors:**
23+
You have two main options for automatically generating API documentation from your OpenAPI spec:
24+
25+
### Using Anchors
26+
Add the OpenAPI spec to an anchor in your `mint.json` to generate pages under that section:
1827

1928
```json {5}
2029
{
2130
"anchors": [
2231
{
2332
"name": "API Reference",
24-
"openapi": "/path/to/openapi.json",
33+
"openapi": "/path/to/openapi.json", // Local path or URL
2534
"url": "api-reference",
2635
"icon": "square-terminal"
2736
}
2837
]
2938
}
3039
```
3140

32-
![](/images/anchors-autogeneration-anchors.png)
41+
<Frame>
42+
<img src="/images/anchors-autogeneration-anchors.png" alt="OpenAPI Anchor Generation Example" />
43+
</Frame>
3344

34-
**Example with Tabs:**
45+
### Using Tabs
46+
Alternatively, add the spec to a tab to organize the generated pages under that tab:
3547

3648
```json {6}
3749
{
@@ -45,108 +57,75 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta
4557
}
4658
```
4759

48-
![](/images/autogeneration-with-tabs.png)
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.
60+
<Frame>
61+
<img src="/images/autogeneration-with-tabs.png" alt="OpenAPI Tab Generation Example" />
62+
</Frame>
5863

59-
* `version`: The `version` value from the anchor or tab, if present.
64+
### Generated Page Metadata
65+
Auto-generated pages will include the following metadata by default:
6066

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.
67+
- **Title**: Uses the OpenAPI operation's `summary` field, or generates one from the HTTP method and endpoint
68+
- **Description**: Uses the OpenAPI operation's `description` field if present
69+
- **Version**: Inherits the `version` from the parent anchor or tab if specified
6270

63-
## Create MDX files for API pages
71+
## Custom MDX Pages
6472

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).&#x20;
73+
For more control over your API documentation, you can create individual MDX pages for each operation.
6674

67-
![](/images/elevenlabs-mdx-autogeneration-example.png)
75+
### Why Create Custom Pages?
76+
Custom MDX pages allow you to:
77+
- Customize page metadata
78+
- Add supplementary content and examples
79+
- Control which operations to include
80+
- Organize pages in a custom order
6881

69-
### Autogenerate files
70-
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.
72-
73-
Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping)
74-
autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the
75-
OpenAPI document in your codebase.
82+
### Using the Scraper
83+
For large APIs, manually creating pages can be time-consuming. Use our scraper tool to automate this process:
7684

7785
```bash
86+
# Basic usage
7887
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
79-
```
80-
81-
Add the `-o` flag to specify a folder to populate the files into. If a folder is
82-
not specified, the files will populate in the working directory.
8388

84-
```bash
89+
# Specify output directory
8590
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
8691
```
8792

88-
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-
9593
<Note>
96-
If your OpenAPI document is invalid, the files will not autogenerate.
94+
The scraper requires a valid OpenAPI document. Invalid specs will cause the generation to fail.
9795
</Note>
9896

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-
<Snippet file="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.
97+
### Manual Page Creation
98+
You can also create pages manually by referencing OpenAPI operations in your page metadata:
11099

111100
<CodeGroup>
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-
```
125-
</CodeGroup>
101+
```md Single OpenAPI File
102+
---
103+
title: "Get Users"
104+
openapi: "GET /users"
105+
---
106+
```
126107

127-
<br />
108+
```md Multiple OpenAPI Files
109+
---
110+
title: "Get Users"
111+
openapi: "/path/to/openapi-1.json GET /users"
112+
---
113+
```
114+
</CodeGroup>
128115

129116
<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.
117+
The method and path must exactly match your OpenAPI specification. Mismatches will result in empty pages.
133118
</Note>
134119

135-
## Create MDX files for OpenAPI schemas
120+
## Schema Documentation
136121

137-
Mintlify also allows you to create individual pages for any OpenAPI schema
138-
defined in an OpenAPI document's `components.schemas` field:
122+
### Creating Schema Pages
123+
Generate standalone pages for your OpenAPI schemas defined in `components.schemas`:
139124

140-
<CodeGroup>
141-
```md Example
142-
---
143-
openapi-schema: OrderItem
144-
---
145-
```
146-
147-
```md Format
148-
---
149-
openapi-schema: "schema-key"
150-
---
151-
```
152-
</CodeGroup>
125+
```md
126+
---
127+
openapi-schema: "OrderItem"
128+
---
129+
```
130+
131+
This automatically creates a page documenting the structure and properties of your schema.

‎development.mdx‎

Lines changed: 67 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,17 @@ title: 'Local Development'
33
description: 'Preview changes locally to update your docs'
44
---
55

6+
## Prerequisites
7+
68
<Info>
9+
Please make sure you have **Node.js version 19 or higher** installed before proceeding with the setup.
10+
</Info>
711

8-
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
12+
## Installation
913

10-
</Info>
14+
### Installing Mintlify CLI
1115

12-
**Step 1**: Install Mintlify:
16+
You can install Mintlify globally on your system using your preferred package manager:
1317

1418
<CodeGroup>
1519

@@ -27,13 +31,9 @@ description: 'Preview changes locally to update your docs'
2731

2832
</CodeGroup>
2933

30-
**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:
31-
32-
```bash
33-
mintlify dev
34-
```
34+
### Alternative Installation
3535

36-
Alternatively, if you do not want to install Mintlify globally you can use a run script available:
36+
If you prefer not to install Mintlify globally, you can use it directly through package manager execution commands:
3737

3838
<CodeGroup>
3939
```bash npm
@@ -51,31 +51,47 @@ Alternatively, if you do not want to install Mintlify globally you can use a run
5151
</CodeGroup>
5252

5353
<Warning>
54-
Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
54+
If you're using Yarn's "dlx" command, note that it requires Yarn version >2. Learn more about dlx [here](https://yarnpkg.com/cli/dlx).
5555
</Warning>
5656

57-
A local preview of your documentation will be available at `http://localhost:3000`.
57+
## Running Locally
58+
59+
### Starting the Development Server
60+
61+
1. Navigate to your docs directory (where the `mint.json` file is located)
62+
2. Run the following command:
63+
64+
```bash
65+
mintlify dev
66+
```
67+
68+
Your documentation preview will be available at `http://localhost:3000`.
5869

59-
### Custom Ports
70+
### Port Configuration
6071

61-
By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
72+
#### Default Port
73+
74+
By default, Mintlify runs on port 3000. You can customize this using the `--port` flag:
6275

6376
```bash
6477
mintlify dev --port 3333
6578
```
6679

67-
If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
80+
#### Port Conflicts
81+
82+
If your specified port is already in use, Mintlify will automatically try the next available port:
6883

69-
```md
84+
```bash
7085
Port 3000 is already in use. Trying 3001 instead.
7186
```
7287

73-
## Mintlify Versions
88+
## Maintenance
7489

75-
Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
90+
### Version Management
7691

77-
<CodeGroup>
92+
The CLI version needs to match Mintlify's platform version. If you notice discrepancies between local and production previews, update your CLI:
7893

94+
<CodeGroup>
7995
```bash npm
8096
npm i -g mintlify@latest
8197
```
@@ -87,45 +103,59 @@ Please note that each CLI release is associated with a specific version of Mintl
87103
```bash pnpm
88104
pnpm up --global mintlify
89105
```
90-
91106
</CodeGroup>
92107

93-
## Validating Links
108+
### Link Validation
94109

95-
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
110+
Check for broken references in your documentation using:
96111

97112
```bash
98113
mintlify broken-links
99114
```
100115

101-
## Deployment
116+
## Development Tools
117+
118+
### Code Editor Setup
102119

103-
If the deployment is successful, you should see the following:
120+
For the best development experience, we recommend:
121+
122+
1. [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting
123+
2. [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting
124+
125+
### Deployment Verification
126+
127+
After a successful deployment, you should see a confirmation screen:
104128

105129
<Frame>
106130
<img
107131
className="rounded-md"
108132
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
133+
alt="Deployment success screen showing all checks passed"
109134
/>
110135
</Frame>
111136

112-
## Code Formatting
113-
114-
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
115-
116137
## Troubleshooting
117138

118139
<AccordionGroup>
119-
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
120-
121-
This may be due to an outdated version of node. Try the following:
122-
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
123-
2. Upgrade to Node v19 or higher.
124-
3. Reinstall mintlify: `npm install -g mintlify`
140+
<Accordion title='Module Loading Error (Sharp)'>
141+
If you encounter the error: "Could not load the sharp module using the darwin-arm64 runtime", follow these steps:
142+
143+
1. Remove existing Mintlify installation:
144+
```bash
145+
npm remove -g mintlify
146+
```
147+
2. Upgrade Node.js to v19 or higher
148+
3. Reinstall Mintlify:
149+
```bash
150+
npm install -g mintlify
151+
```
125152
</Accordion>
126153

127-
<Accordion title="Issue: Encountering an unknown error">
128-
129-
Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
154+
<Accordion title="Unknown Errors">
155+
For unexpected errors:
156+
157+
1. Navigate to your device's root directory
158+
2. Delete the ~/.mintlify folder
159+
3. Run `mintlify dev` again
130160
</Accordion>
131-
</AccordionGroup>
161+
</AccordionGroup>

0 commit comments

Comments
 (0)