Skip to main content

About Extension Components

The APIMatic's VS Code extension makes two major contributions to the VS Code:

This document covers each of the above component in detail.

APIMatic API Explorer View Container

You will find all important views associated with the extension, in the APIMatic API Explorer view located in the Activity Bar. These views allow for easy API file navigation as well as for understanding validation issues better.

APIMatic API Explorer

Full list of views associated with the APIMatic API Explorer view container is given below:

  1. Workspace File Navigator View

  2. Workspace Validation Summary View

  3. Violations at Current File Position View

  4. Learn More View

  5. Manage Session View

  6. Report Issues View

    APIMatic API Explorer Views

Workspace File Navigator View

The main purpose of this view is to make it easier for users to navigate through and work with files and folders involved in the API workspace.

Workspace File Navigator

Open Files in the Editor

Clicking on a file's name will open it in the VS Code Editor. However, only textual or non-binary files can be opened this way.

Edit Files and Folders

The files and folders in this view appear as read-only since basic file related functionalities (e.g. renaming, deleting or adding) are already available in the VS Code's Explorer view. If you still wish to perform some file/directory related actions, click on the pencil (✏️) icon that becomes visible on hover near the navigator view's title or the file/directory name:

  • Edit option near the file/directory name:

    Edit File/Directory

  • Edit option near the File Navigator view title:

    Edit Workspace Folder

Clicking on this will switch the active view to the Explorer and highlight your selected file/directory name in it so you can quickly perform required actions there.

Edit in Explorer

An alternative approach to doing this would be to open the context menu for a file/folder and clicking on the Edit option:

Edit File/Directory via Context

Main API File Highlighting and Labelling

To distinguish API definition's main entry files from other files, they are given a default background color and have an api label attached after the file name:

Main File Highlight

Add an APIMatic Metadata File

If your API workspace lacks an APIMatic Metadata file, the view offers an option to quickly add one:

  • Hover near the Workspace File Navigator view title and select the Add APIMatic Metadata Configuration File option as shown below:

    Add Metadata File

  • You will be asked to select one or more configuration objects to initialize by default. Pick as per requirements:

    Metadata File Configuration

  • A metadata file with selected configurations will be instantly added in the API workspace:

    Metadata File Added

APIMatic Metadata Files Labelling

To distinguish APIMatic's Metadata files in the view from other files, a meta label is attached after their file name:

Metadata File Label

Reveal All Main API Files

If you are dealing with multiple API definitions in your API workspace or your main entry file for the API definition is nested within a folder, you can use the reveal feature to bring all main API files in the workspace directories into view. This will uncollapse all collapsed directory names to reveal nested items.

  • Hover near the Workspace File Navigator view title and click on the three horizontal dots (...) in the top right corner. Select the Reveal All Main API Files option:

    Reveal Main Files

  • This will instantly expand all directories and reveal all highlighted main API files:

    Main Files Revealed

Collapse All Folders

To quickly collapse all folders in the API workspace, hover near the Workspace File Navigator view title and click on the collapse all icon:

Collapse All

All expanded directories will instantly be closed.

Refresh View

If the files/folders involved in the API workspace have changed outside the VS Code extension, you can refresh the navigator view to get updated information for each file and folder. This can be done by hovering near the Workspace File Navigator view title and clicking on the refresh (🔃) icon:

Refresh File Navigator

This will reload the files and folders as well as re-validate the workspace.

Workspace Validation Summary View

This view shows a summary of validation status of the complete API workspace.

Workspace Validation Summary View

Generate Reports

To share the validation summary with external stakeholders, you can generate one or more reports by clicking on the report (🗒️) button visible in the top right corner when you hover on the Workspace Validation Summary view title:

Generate Audit Report

To learn more about generating reports, please check out our documentation here.

Validation Status

The overall pass/fail status is shown in the Status property. Possible values and what they mean are defined below:

PassedAll files in the API workspace are valid and have no issues. You can safely proceed to generating desired output from your API definition(s).
Passed With WarningsOne or more files in the API workspace have some warnings but this won't be a blocker for generating an output from your API definition(s).
Failed With ErrorsOne or more files in the API workspace contain errors that need to be resolved before you can generate any output for your API definition(s).
Failed With Blocking ErrorsOne or more files in the API workspace contain blocker issues that are preventing the validation process from completing. Once these issues are resolved the validation process will resume and may detect more issues. No output can be generated from the API definition(s) unless all blocking issues (current and any upcoming) are resolved.

The overall status is decided based on the severity of messages logged for the API workspace.


Labelled as Percentage Score, this is another measure to help you quickly determine how good or bad your API workspace definitions are doing in terms of number of issues, severity, type of issues, etc. You should aim for a score above 80% to get a better output from your API definition(s) in any API tool.

Total Messages

Labelled as Total, this property shows the total number of issues present across all files in your API workspace. This includes a sum of issue types and their particular instances.

Messages by Severity

Validation issues/messages are grouped based on severity level to help you tackle blocker issues first followed by warnings and so on. The severity level is followed by a count of message instances that are of the selected severity level.

Validation/Linting Messages

Issues are also grouped based on whether they are validation messages or linting messages. The total count of message instances of the selected type is mentioned at the end of the label.

Instances Grouped by Message

At the top-level, the messages are grouped either by severity or based on whether they are validation or linting messages. Instances of messages belonging to these groups are further grouped on the message value. Label of such groups show the message value followed by a count of instances belonging to the message. This grouping can be useful if you want to tackle a particular issue and all of its instances first before moving on to another issue.

If you want to understand what a message means, view hints to resolve the issue or just want to see more details about the rule that the message belongs to, you can click on the (?) visible when you hover near the message value. This should open the Learn More View with all relevant details.

Message instances are likely to have a file and line/path information attached to them. Clicking on an instance will take you to where the instance is located by first opening the target file and then highlighting the target line in the file. In some cases, where the instance may not be directly associated with a file, a path information will be available and clicking on the instance will not have any effect.

Violations at Current File Position View

The information shown on hovering over a squiggly in the Editor, when working with an API workspace file, is quite limited. It is also possible that multiple issues exist at the squiggly point which makes the hover messages more confusing especially since they lack any severity information:

Multi Messages Editor

To make it easier to tackle issues at a particular point in the file open in the Editor, we added a Violations at Current File Position view. This view updates itself with every cursor position change in the Editor and shows a list of issues/violations applicable at that position. For each issue, we provide additional contextual information as well to help users resolve issues more efficiently.

Current Violations View

Cursor Position

This property shows the line number and position of your cursor in the active Editor.


This property shows the list of issues applicable at the current cursor position in the Editor. The Violations property name is followed by a total count of issues nested inside it.

The data that is available for each violation is described in the next few sections.

Violation Message

For each violation the root node represents the message associated with the issue, visible to you when you hover over the squiggly in the editor and which describes the problem in few short words.

If you want to understand what a violation message means, view hints to resolve the issue or just want to see more details about the rule that the message belongs to, you can click on the (?) visible when you hover near a violation message value. This should open the Learn More View with all relevant details.

Violation Severity

Labelled as Severity, this property indicates the severity level of the message.

Violation Location in File

Labelled as Location in File, this property shows the line number and position range at which the issue exists i.e. unlike the cursor position which indicates a single point in the file, this location will contain full information of starting and ending line numbers and positions. If you click on the location information it will also highlight the specific range in the file.

Violation Path

Labelled as Path, this property shows either the breadcrumb path to the particular location or the JSON reference path, whatever is available.

Violation Contextual Data

Each issue may have dynamic key-value pairs attached with it that represents additional context for the issue:

Contextual Data

Violation Call Trees

Labelled as Call Tree, this property contains complete data about components referencing the current component in question, using $ref. As the name suggests, this information is represented as a "tree" where the root node is the current component containing the issue and child nodes are components that are directly referencing this component using $ref. Inner children of these child nodes will be nodes directly referencing those nodes using $ref and so on. The purpose of a call tree is to help you understand scenarios where the issue may have originated based on how it was referenced.

Here is an example of an OpenAPI file where the same object is incorrectly referenced as both a Parameter Object and as a response Schema Object:

Incorrect Reference

Due to this, the referenced component has an error shown at the required property value:

Referenced File

This required property is allowed to be a boolean if it is referenced as a Parameter Object. But the same required property can't be a boolean if it is referenced as a Schema Object. This implies that the error on the property required is due to the incorrect response Schema Object reference:

Incorrect Response Reference

The call tree helps confirm this by showing only the incorrect response Schema Object reference as the root cause for the error on the required property:

Call Tree

In this way, if the response schema reference is removed, the issue will be resolved. Without a call tree, it would have been difficult to understand the origin of the issue in the referenced component.

Learn More View

As the name suggests, this view helps you learn more about a particular issue by providing details about the rule associated with the issue. The information listed here is also available for each rule in our official documentation of each ruleset. The goal of providing the same information within the extension is to help save the user's time in searching for details to better understand the issue and to easily view hints for resolving it efficiently.

Learn More View

A detailed breakdown of each property in this view is described below:

Rule IdUnique identifier of the rule in a ruleset.
Ruleset IdUnique identifier of the ruleset to which the rule belongs.
Rule TypeWhether the rule is a validation rule or a linting rule.
DescriptionDescribes what the rule expects/dictates.
HintsTips that can be followed to resolve any issues that occur when the rule is violated.
LinksExternal links that can help provide more information for understanding the issues that occur when the rule is violated.
Possible Impact OnA list of APIMatic products where you can expect your output to be negatively impacted if this rule is violated.
CategoryA broad semantic category of the rule in the ruleset.
TagsKeywords or tags associated with the rule.
MessageThe message displayed to the user (unless overridden) if this rule is violated.
Default SeverityThe default severity of the message which is displayed when the rule is violated. This severity may be overridden via configuration.
Rule System TypeThe rule system that this rule belongs to.
Rule CodeA short, unique identifier of the rule among all available rulesets.

Open Rule Details in This View

Details of a rule associated with an issue can be opened from:

Expand Rule Details

If you feel the need to repeatedly consult the Learn More view details or are having trouble navigating through the details because of the small view area, you can choose to expand the details and open them in a separate editor tab instead. To do this, simply hover near the view title and click on the Expand Validation Rule Details button:

Expand Learn More

The details will open in a separate tab as follows:

Expanded Learn More

Copy Rule and Ruleset Id

While configuring validation, you may feel the need to find out a particular rule's id or its ruleset id. The Learn More view can be helpful in such cases as it allows you to copy the relevant ids. Simply hover near the id values in the view and click on the clipboard (📋) icon to copy the value:

Copy Rule Id

Clear the View

To clear the details visible in the view, hover near the view title and click on the Clear Validation Rule Details button in the top right corner:

Clearing the View

After clicking, details of the rule will be removed from the view until you select any other rule.

Manage Session View

This view contains details about your current session including your name and email information. This information is obtained after you authorize the extension using your APIMatic account:

Manage Session View

Close the Session

If you wish to log out from the extension, you can click on the Close Session button from the right corner of the view title:

Close Session

You will be asked to confirm this action before proceeding:

Close Session Confirmation

To use the extension after closing the session, you will need to authorize yourself with APIMatic again.


Closing the extension session will only remove your access to the extension functionality and erase personal information from it e.g. name and email, but will not log you out of your APIMatic account elsewhere.

Report Issues View

If you ran into any problems while using the extension or would simply like to share any feedback that can help improve your experience in any way, this view can provide you with all relevant links:

Report Issues

Status Bar Actions

The APIMatic VS Code extension offers various workspace and editor level actions in the status bar:

Status Bar

Workspace Actions

In VS Code, actions that affect the whole workspace are located on the left. This is also the case for workspace actions provided by APIMatic in the extension:

Status Bar Workspace Actions

Following workspace actions are available:

The status bar may also display status messages from time to time when one of the above processes are running:

Auto Fix Running

Editor Reference Documentation Action

In VS Code, actions that are contextual or language-specific go towards the right. Accordingly, when working with API files in the Editor, the extension can display the API specification format name with a (📖) icon in the right end of the status bar as shown below:

Status Bar Editor Actions

Clicking on it will open the reference documentation linked to the specification. Documentation compatible with VS Code (e.g. GitHub URLs) will open within the extension. Others may use your default web browser to show the documentation:

Reference Documentation