VS Code APIMatic Extension Overview
The APIMatic API Definition Validator VS Code extension is currently in alpha.
APIMatic offers a VS Code extension that enables you to easily validate and lint your API definition files in any of the supported formats. The API definition files are not only validated against standard checks but also linted against checks required for smoother SDK generation, Developer Experience Portal generation and API specification format transformation.
The extension provides a richer validation experience by offering dedicated views with messages organized for easy navigation, contextual data for each issues (e.g. line and path information, call tree to trace origin, etc.) as well as detailed descriptions, hints and reference documentation links for resolving issues quickly. It also supports auto-fixing commons issues found in OpenAPI v3 files (e.g. inline schemas) that hinders output quality or generation. You can also generate summary reports in multiple formats (PDF, HTML, JSON, Markdown) for sharing with any relevant stakeholders.
Once your API definition is ready, you can easily export them to your APIMatic Dashboard for SDK/DX portal generation without needing to leave the VS Code extension. Additionally, you can also perform transformation to a selected export format and obtain the output within your workspace.
Installation Guide
You can install the VS Code extension in a few quick steps as described below.
Pre-Requisites:
To install and run the APIMatic's API definition validator extension, you need to ensure that you have the following:
Visual Studio Code version 1.57.0 or above. Use download link.
Stable internet connection.
Step 1: Download the APIMatic VS Code Extension
Download the extension's .VSIX file by clicking on the Download Now button from your APIMatic Dashboard top banner.
The file should start downloading immediately after.
Step 2: Install the APIMatic VS Code Extension
Open VS Code
Extensionsview in the Activity Bar.Click on the 3 horizontal dots on the top right corner of the
Extensionsview and click onInstall from VSIX....
Select the downloaded VSIX file from your system. The installation will begin. On successful installation, the APIMatic API Explorer should be visible in the Activity Bar:
For further information regarding installation of a VS Code extension, please visit the official documentation here.
Getting Started - How to Validate an API Definition
Step 1: Open an API Workspace Folder
To validate your API definition, you need to have a dedicated workspace folder open in your VS Code where you will work with one or more files associated with the API definition itself. If you have an existing folder in your system that contains an API definition (e.g. OpenAPI), you can also open that in your VS Code.
For this guide, we use an empty workspace folder as shown below:
Navigate to the APIMatic API Explorer view in the Activity Bar and click on Use Current Workspace Folder to select current folder as your API workspace.
Step 2: Import an API Definition
If your workspace already contains an API definition, its main entry file will be auto-detected and the validation should start automatically. However, for our current example the workspace does not contain any API definition, therefore, a welcome view is shown with various options to create/import an API definition.
We will import a JSON sample file using the relevant options as shown below:
Step 3: Fix any issues in the API Definition
As soon as an API definition is added to the workspace, it will be auto-validated. You can also manually trigger validation by saving your API definition files.
When the validation completes, the side views, Editor and Problems view will be populated with relevant data to help you tackle all issues.
Once you have resolved all blocker issues, you can export your API definition to your APIMatic Dashboard to start generating an SDK or a Developer Experience Portal.
Capabilities
The VS Code extension offers the following:
- Setting up an API workspace.
- Validating an API workspace.
- Auto-fixing an API workspace.
- Building an API workspace.
- Exporting an API workspace to APIMatic Dashboard.
- Transforming API workspace specification format.