API specifications

Import, organize, and manage OpenAPI and AsyncAPI specification files in the web editor.

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.

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.