Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@
"editor/pages",
"editor/media",
"editor/navigation",
"editor/api-specs",
"editor/configurations",
"editor/live-preview",
"editor/collaborate",
Expand Down Expand Up @@ -421,6 +422,7 @@
"fr/editor/pages",
"fr/editor/media",
"fr/editor/navigation",
"fr/editor/api-specs",
"fr/editor/configurations",
"fr/editor/live-preview",
"fr/editor/collaborate",
Expand Down Expand Up @@ -767,6 +769,7 @@
"es/editor/pages",
"es/editor/media",
"es/editor/navigation",
"es/editor/api-specs",
"es/editor/configurations",
"es/editor/live-preview",
"es/editor/collaborate",
Expand Down Expand Up @@ -1113,6 +1116,7 @@
"zh/editor/pages",
"zh/editor/media",
"zh/editor/navigation",
"zh/editor/api-specs",
"zh/editor/configurations",
"zh/editor/live-preview",
"zh/editor/collaborate",
Expand Down
143 changes: 143 additions & 0 deletions editor/api-specs.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
---
title: "API specifications"
description: "Import, organize, and manage OpenAPI and AsyncAPI specification files in the web editor."
keywords: ["editor", "api", "openapi", "asyncapi", "specifications"]
---

Manage your API specification files directly in the web editor. Import OpenAPI and AsyncAPI specifications, organize them in folders, and link them to your navigation.

<Frame>
<img
src="/images/editor/api-specs-light.png"
alt="API Specs view in the editor sidebar in light mode."
className="block dark:hidden"
/>
<img
src="/images/editor/api-specs-dark.png"
alt="API Specs view in the editor sidebar in dark mode."
className="hidden dark:block"
/>
</Frame>

## Access API specs view

Open the API Specs view from the editor sidebar:

1. Click **Configurations** in the left sidebar
2. Select **API Specifications** from the configurations menu

The API Specs view displays all OpenAPI and AsyncAPI specification files in your documentation repository.

## Import specification files

Add OpenAPI or AsyncAPI specification files to your documentation:

1. In the API Specs view, click the **Add** button
2. Select **Import specification**
3. Choose one or more JSON or YAML files from your computer

Check warning on line 37 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L37

Use 'yaml' instead of 'YAML'.
4. The editor validates each file and imports valid OpenAPI or AsyncAPI specifications

The editor automatically detects the specification type (OpenAPI or AsyncAPI) and displays appropriate icons and metadata.

### Supported formats

- **OpenAPI**: JSON or YAML files with `openapi` field (versions 3.0+)

Check warning on line 44 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L44

Use 'yaml' instead of 'YAML'.
- **AsyncAPI**: JSON or YAML files with `asyncapi` field (versions 2.0+)

Check warning on line 45 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L45

Use 'yaml' instead of 'YAML'.

## Organize specs in folders

Create folders to organize your API specifications:

1. Click the **Add** button in the API Specs view
2. Select **New folder**
3. Enter a folder name
4. Press Enter to create the folder

### Move specs with drag-and-drop

Reorganize your specifications by dragging them:

- Drag a file or folder to reorder it
- Drop a file onto a folder to move it inside
- Drop a file in the root area at the bottom to move it to the top level

## Configure navigation items

Link API specifications to your navigation items using the configure sheet:

1. Select a page or navigation item
2. Click the settings icon to open the configure sheet
3. Scroll to the **OpenAPI** or **AsyncAPI** field
4. Choose between **File** or **URL** mode:
- **File**: Select a specification file from your repository
- **URL**: Enter a URL to an external specification file

### File mode

Select a specification file from your repository:

1. Click the **File** button
2. Choose a file from the dropdown menu
3. Click the arrow icon to preview the specification in the API Specs view

### URL mode

Check warning on line 83 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L83

'URL mode' should use sentence-style capitalization.

Link to an external specification file:

1. Click the **URL** button
2. Enter the full URL to your specification file (e.g., `https://api.example.com/openapi.json`)

Check warning on line 88 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L88

Use 'for example' instead of 'e.g.'.
3. The URL must start with `http://` or `https://`

<Note>
You can only set either OpenAPI or AsyncAPI for a navigation item, not both. The fields disable each other when one is set.

Check warning on line 92 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L92

Use 'turn off' or 'off' instead of 'disable'.

Check warning on line 92 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L92

In general, use active voice instead of passive voice ('is set').
</Note>

## Preview API spec files

View the contents of your specification files:

1. Click a specification file in the API Specs view
2. The file opens in read-only preview mode
3. Review the JSON or YAML content

Check warning on line 101 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L101

Use 'yaml' instead of 'YAML'.

The preview displays syntax highlighting and formatting for easy reading.

## Manage specs

Configure and manage individual specification files:

1. Click the settings icon on a file or folder
2. The configure sheet displays metadata:
- **Spec type**: OpenAPI or AsyncAPI with version number
- **Tags**: Number of tags defined in the specification
- **Paths/Channels**: Number of API endpoints or channels
- **File size**: Size of the specification file
- **File path**: Full path in your repository

### Rename files and folders

Change the name of a file or folder:

1. Open the configure sheet for the item
2. Edit the name in the **File name** or **Folder name** field
3. Click **Save changes**

### Delete files and folders

Remove specification files or folders:

1. Open the configure sheet for the item
2. Click **Delete file** or **Delete folder** at the bottom
3. Confirm the deletion

Deleting a folder removes all files and subfolders inside it.

Check warning on line 133 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L133

Did you really mean 'subfolders'?

## Copy file paths

Copy the path of a specification file to use in configuration:

1. Right-click a file in the API Specs view
2. Select **Copy path** from the menu
3. The file path is copied to your clipboard

Check warning on line 141 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L141

Use 'path' instead of 'file path'.

Check warning on line 141 in editor/api-specs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/api-specs.mdx#L141

In general, use active voice instead of passive voice ('is copied').

Use the copied path when configuring OpenAPI or AsyncAPI fields in your navigation items.
13 changes: 13 additions & 0 deletions editor/configurations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@
Set your site's identity and how it appears to visitors.

- **Docs title**: The name of your documentation. Appears in browser tabs and search results.
- **Description**: Brief summary of your documentation. Used for SEO and site metadata.

Check warning on line 27 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L27

Spell out 'SEO', if it's unfamiliar to the audience.
- **Favicon**: Small icon that appears in browser tabs. Upload ICO, PNG, GIF, or JPG files.

Check warning on line 28 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L28

Use 'favicon' instead of 'Favicon'.

Check warning on line 28 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L28

Spell out 'ICO', if it's unfamiliar to the audience.

Check warning on line 28 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L28

Spell out 'PNG', if it's unfamiliar to the audience.

Check warning on line 28 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L28

Use 'png' instead of 'PNG'.

Check warning on line 28 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L28

Spell out 'GIF', if it's unfamiliar to the audience.

Check warning on line 28 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L28

Spell out 'JPG', if it's unfamiliar to the audience.
- **Theme**: Choose a [theme](/customize/themes) for your documentation's overall appearance.

## Customize colors and appearance
Expand All @@ -35,10 +35,10 @@
- **Primary color**: The main accent color used throughout your site for links, buttons, and highlights.
- **Light mode color**: Accent color variation for light mode. How themes apply this varies by theme.
- **Dark mode color**: Accent color variation for dark mode. How themes apply this varies by theme.
- **Logo**: Your brand logo. Upload SVG, PNG, or JPG files. You can set different logos for light and dark modes.

Check warning on line 38 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L38

Use 'png' instead of 'PNG'.

Check warning on line 38 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L38

Spell out 'PNG', if it's unfamiliar to the audience.

Check warning on line 38 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L38

Spell out 'JPG', if it's unfamiliar to the audience.
- **Logo link**: Where users go when they click your logo. Typically your homepage or marketing site.
- **Background colors**: Set custom background colors for light and dark modes separately.
- **Background image**: Add a background image to your site. Upload PNG, GIF, or JPG files.

Check warning on line 41 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L41

Use 'png' instead of 'PNG'.

Check warning on line 41 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L41

Spell out 'PNG', if it's unfamiliar to the audience.

Check warning on line 41 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L41

Spell out 'GIF', if it's unfamiliar to the audience.

Check warning on line 41 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L41

Spell out 'JPG', if it's unfamiliar to the audience.
- **Background decoration**: Apply visual styles to your background image.
- **Theme toggle**: Show or hide the light/dark mode switcher for users.
- **Default theme**: Set whether your site loads in light or dark mode by default.
Expand All @@ -47,7 +47,7 @@

Replace default fonts with your brand's typography.

- **Default font**: The base font family and weight for all text. Provide a source URL and format (WOFF or WOFF2).

Check warning on line 50 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L50

Spell out 'WOFF', if it's unfamiliar to the audience.
- **Heading font**: Font family and weight specifically for headings (h1, h2, etc.). Set separately from body text.
- **Body font**: Font family and weight for body text and paragraphs.

Expand All @@ -57,8 +57,8 @@

Add navigation elements to the top of your site.

- **Navbar button**: Add a primary call-to-action button in your header. Set the button type, label, and destination URL.

Check warning on line 60 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L60

Use 'navbar' instead of 'Navbar'.
- **Navbar links**: Add additional navigation links in your header. Each link includes text and a URL.

Check warning on line 61 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L61

Use 'navbar' instead of 'Navbar'.

## Configure footer

Expand All @@ -74,7 +74,7 @@
- **Thumbnail background**: Set a custom background image for page thumbnails and social previews.
- **Thumbnail appearance**: Control how thumbnails display.
- **Thumbnail font**: Set a custom font for text in thumbnails.
- **Page eyebrow**: Add small labels above page titles.

Check warning on line 77 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L77

Use 'preceding' instead of 'above'.
- **Code block theme**: Choose the syntax highlighting theme for code blocks.
- **LaTeX support**: Enable mathematical notation rendering with LaTeX.

Expand All @@ -82,8 +82,21 @@

Customize the search experience.

- **Search placeholder**: The text that appears in the search box before users type. Default is "Search or ask...".

Check warning on line 85 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L85

Commas and periods go inside quotation marks.

Check warning on line 85 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L85

In general, don't use an ellipsis.

## Configure API specifications

Link OpenAPI and AsyncAPI specification files to navigation items.

- **OpenAPI**: Select a specification file from your repository or enter a URL to an external OpenAPI file. Choose between file and URL modes using the toggle buttons.
- **AsyncAPI**: Select a specification file from your repository or enter a URL to an external AsyncAPI file. Choose between file and URL modes using the toggle buttons.

<Note>
You can only set either OpenAPI or AsyncAPI for a navigation item, not both. Setting one disables the other field.
</Note>

When using file mode, click the arrow icon next to a selected file to preview it in the API Specs view. Use the trash icon to clear the field.

## Add analytics and integrations

Connect analytics and third-party tools to your documentation.
Expand All @@ -91,13 +104,13 @@
Track visitor behavior with:
- **Amplitude, Mixpanel, Heap**: Product analytics platforms
- **Google Analytics, Google Tag Manager**: Web analytics
- **PostHog, Plausible, Fathom**: Privacy-focused analytics

Check warning on line 107 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L107

Use 'Posthog' instead of 'PostHog'.
- **Segment, Hightouch**: Customer data platforms
- **Hotjar, LogRocket**: Session replay and heatmaps

Check warning on line 109 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L109

Did you really mean 'Hotjar'?

Check warning on line 109 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L109

Did you really mean 'heatmaps'?
- **Microsoft Clarity**: User behavior analytics
- **Intercom**: Customer messaging
- **Clearbit, Koala**: Visitor identification

Additional integrations:
- **Telemetry**: Enable or disable usage telemetry

Check warning on line 115 in editor/configurations.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/configurations.mdx#L115

Use 'turn off' or 'off' instead of 'disable'.
- **Cookies**: Set custom cookie key and value pairs
4 changes: 4 additions & 0 deletions editor/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
alt="Decorative image in dark mode"
/>

Create and edit documentation directly in your browser with the web editor. Work on content visually to see real-time previews or in Markdown; manage your site structure with drag-and-drop components; and publish changes using Git workflows.

Check warning on line 20 in editor/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/index.mdx#L20

Use semicolons judiciously.

Check warning on line 20 in editor/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

editor/index.mdx#L20

Use semicolons judiciously.

## Key features

Expand All @@ -42,6 +42,10 @@
Upload and use images in your documentation.
</Card>

<Card title="Manage API specs" icon="file-json" horizontal href="/editor/api-specs">
Import and organize OpenAPI and AsyncAPI specifications.
</Card>

## Publish and collaborate

<Card title="Publish changes" icon="rocket" horizontal href="/editor/publish">
Expand Down
Loading