API Contractor for Visual Studio Code
An extension for Visual Studio Code that provides intellisense, validation and other features
for the API contracts editing using AML Language Server (ALS)
and previewing with the Mulesoft API Console.
What types of documents are supported?
See supported types of documents: https://github.com/aml-org/als#what-is-als
Notes on JS and Java server variants
- Java is required only when a path to the ALS server jar is specified in the
apiContractor.jvm.jarPath setting. The latest jar file can be downloaded from the extension's github repository.
- If you are experiencing performance issues with the JS version of the ALS server - consider using Java version.
- If you are working with large API contracts and have limited amount of RAM, consider using OpenJ9 and configuring the JVM by specifying arguments in the
API Contractor: Restart language server - Restarts the client and language server.
API Contractor: Preview current API file - Opens current API file in the API console.
API Contractor: Set current API file as root file - Writes the
exchange.json file to workspace root with the relative path to current API file.
API Contractor: Convert current API file - Shows the option menus with available conversion formats and syntaxes and converts the current API file according to the selections.
apiContractor.trace.server - Traces the communication between VS Code and the language server.
apiContractor.autoDetectRootApi - Enables automatic detection and selection of the root API file.
apiContractor.autoRenameRefs - Configures automatic rename of the referenced files. Works only when the workspace has the root API file set.
apiContractor.notification.noMainApiFileSet - Enables notification when no main API file is set.
apiContractor.jvm.jarPath - A path to JVM binary of the ALS. Note that VS Code must be reloaded when changing this value.
apiContractor.jvm.arguments - Uses provided arguments to execute the JVM version of the language server.
apiContractor.autoReloadApiPreviewOnSave - Enables automatic reload of the API file preview when it is saved. API file preview tabs must be reopened when this setting is changed. Note: in structured projects where root API file is set, the API file preview will be also reloaded when its referenced files are saved.
Language functionality relies on LSP support in ALS. You
can find currently supported features there.
Setting a root API file
API Contractor: Set current API file as root file command allows setting the root API file for the current workspace.
As the result, the
exchange.json file will be created in the workspace root and contain a relative path to the main API file.
This enables proper linking and validation for separate JSON/YAML files that are linked to the root API file.
exchange.json file was not found in the workspace during the load or there are multiple API files,
a notification message will appear with a proposal to set a root API file for the workspace. You can enable
automatic detection of the root API file by enabling the
The root API file setting does not limit validation of the files that are not linked to the root API file.
Automatically rename referenced fragments
When the root API file is set, the fragments' references will be automatically updated when their files are renamed.
You can configure this behavior by changing the
API files preview
Currently opened API file can be previewed and tried out with the API Console. A command to invoke API file preview is
API Contractor: Preview current API file.
apiContractor.autoReloadApiPreviewOnSave option is enabled, the API file preview is updated when the previewed API file is saved.
API format conversion
API Contractor: Convert current API file command allows converting currently opened API file. When the command
is invoked, the pick menu will appear with supported conversion formats. After the conversion is done, a new API file
in selected format will appear.
- Due to the differences between formats, some format-specific features may be lost or preserved as metadata in
x-amf tags that need to be post-processed.
- Unused types will be lost during the conversion.
- If there is a file with the same name as the resulting API file, it will be overwritten.
JVM arguments can be provided in the
apiContractor.jvm.arguments option to control the JVM memory management.
If any errors occur and the language server doesn't start after the change of arguments, execute
Developer: Toggle Developer Tools and look for ALS error messages in the
Status bar for the currently selected root API file
If a root API file is selected for current project, the status bar will show a path to it; otherwise,
the status bar will show
No root API file.
When no root API file set:
When root API file set:
When the status bar is clicked, the file selection window will be opened in the current workspace root.
Status bar for the format of currently opened API file
When an API file is opened, its format will be shown in the status bar.
When the status bar is clicked, the
API Contractor: Convert current API file command is invoked.
Current API file preview button
When an API file is opened, a button for previewing the current API file will appear in the editor toolbar.
Pattern error with valid named capture groups
Since the extension uses JVM version of the language server (JS version is experimental), the patterns are validated
according to the Java rules. See Java Class Pattern documentation.
If a named capture group is valid according to the ECMA-262 regular expression dialect, remove it to proceed further with validation, then change it back once the document is valid.
How to enable autocomplete?
To enable autocomplete and snippets on typing, enable the
editor.quickSuggestions setting in VS Code. Otherwise,
Before you start, run
npm install in this folder to install all package dependencies.
- Open VS Code on this folder.
Ctrl+Shift+B and select
npm: compile to compile the extension.
./src/extension.ts and press
Ctrl+Shift+D to switch to debugging menu.
- Click Run and Debug to start debugging.
vsce package in this folder. This will compile and pack the extension into the