From c2f837ecacb9fbb5065164b6fba74c9dd19beb9a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 19:07:45 +0000 Subject: [PATCH 1/7] Update editor/api-specs.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- editor/api-specs.mdx | 143 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 editor/api-specs.mdx diff --git a/editor/api-specs.mdx b/editor/api-specs.mdx new file mode 100644 index 000000000..59278f15f --- /dev/null +++ b/editor/api-specs.mdx @@ -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. + + + API Specs view in the editor sidebar in light mode. + API Specs view in the editor sidebar in dark mode. + + +## 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 +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+) +- **AsyncAPI**: JSON or YAML files with `asyncapi` field (versions 2.0+) + +## 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 + +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`) +3. The URL must start with `http://` or `https://` + + +You can only set either OpenAPI or AsyncAPI for a navigation item, not both. The fields disable each other when one is set. + + +## 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 + +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. + +## 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 + +Use the copied path when configuring OpenAPI or AsyncAPI fields in your navigation items. From 23379f221013feb2537ba6b12d4a4d061671cb67 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 19:08:05 +0000 Subject: [PATCH 2/7] Update editor/configurations.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- editor/configurations.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/editor/configurations.mdx b/editor/configurations.mdx index b1cb23d1b..5d54169e1 100644 --- a/editor/configurations.mdx +++ b/editor/configurations.mdx @@ -84,6 +84,19 @@ Customize the search experience. - **Search placeholder**: The text that appears in the search box before users type. Default is "Search or ask...". +## 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. + + +You can only set either OpenAPI or AsyncAPI for a navigation item, not both. Setting one disables the other field. + + +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. From c4b214cda75a7107f8ac7e78fd522f26e13b8be3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 19:08:16 +0000 Subject: [PATCH 3/7] Update editor/index.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- editor/index.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/editor/index.mdx b/editor/index.mdx index d6c7ec46b..1bc3334ce 100644 --- a/editor/index.mdx +++ b/editor/index.mdx @@ -42,6 +42,10 @@ Create and edit documentation directly in your browser with the web editor. Work Upload and use images in your documentation. + + Import and organize OpenAPI and AsyncAPI specifications. + + ## Publish and collaborate From 4ec8b08a4f44dacfe66a2b717f5ad6fa8917378d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 19:08:34 +0000 Subject: [PATCH 4/7] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 9fcf0c8b7..27676e980 100644 --- a/docs.json +++ b/docs.json @@ -73,6 +73,7 @@ "editor/pages", "editor/media", "editor/navigation", + "editor/api-specs", "editor/configurations", "editor/live-preview", "editor/collaborate", From 9d7b8d12b4124b01e5384272964891cae13c8dbb Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 19:08:43 +0000 Subject: [PATCH 5/7] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 27676e980..a10f1616d 100644 --- a/docs.json +++ b/docs.json @@ -422,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", From fca3e5ee903462a6a6a52685b09c2ae159081e37 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 19:08:46 +0000 Subject: [PATCH 6/7] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index a10f1616d..78d5f1eac 100644 --- a/docs.json +++ b/docs.json @@ -769,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", From efe528638e1308f843b60e368a7238cf3d0f7e30 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 20 Jan 2026 19:08:48 +0000 Subject: [PATCH 7/7] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 78d5f1eac..b176fbeeb 100644 --- a/docs.json +++ b/docs.json @@ -1116,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",