diff --git a/docs.json b/docs.json index 9fcf0c8b7..b176fbeeb 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", @@ -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", @@ -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", @@ -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", 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. 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. 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