OpenAPI VSCode by APIMatic - Validate, Lint, and Auto-Fix

At APIMatic, we process hundreds of thousands of API definitions every year to transform specification formats and generate SDKs and Docs. Interestingly, a big chunk of those API definitions is syntactically correct, but not good enough to generate highly quality code. This is simply because OpenAPI and other popular API specification formats are not built with code generation in mind. We are thrilled to announce the release of our new VS Code extension which comes equipped with over 1200 pre-defined rules to help you effortlessly validate, lint, and auto-fix your API definition files and generate powerful SDKs and documentation.

In this blog, we will discuss in detail why we built this extension in the first place and how it can help you in your API journey. Or if you're eager to get started with the extension, here's the big old download button:

Another Validator! But Why?

This has been the most common question we’ve received so far. There are some great tools in the market, but they have a few shortcomings that make them less ideal for users focused on auto-generating SDKs from their API definitions. Those shortcomings include: 

No dedicated rulesets for code generation

While the existing tools, such as Spectral, have some basic rulesets and plenty of third-party rulesets available in their platform, they do not provide any rulesets out of the box to validate API specifications for code generation purposes.

No enforcement of mandatory standard checks

API specification standards like OpenAPI make some rules mandatory using the MUST/REQUIRED keywords. Some of those rules are quite important, but, unfortunately, not all of them are enforced by available tools, possibly to provide greater flexibility.

Here’s one that disallows keys of reusable components from having anything other than alpha-numeric characters, dashes, periods, and underscores in them:

These keys/names play an important role when generating code. However, I’m able to easily get away with any character in my schema name without any related error/warning in Spectral:

Too much flexibility

All validators including Spectral offer the ability to disable rules as required. In some scenarios, flexibility can be a good thing. But when it comes to generating code, knowing beforehand what rules can negatively affect your output if disabled, can be hard to determine and so this flexibility can be a double-edged sword. You can even end up disabling something important. 

Missing documentation

Nothing is worse than running into a tricky issue and not having any documentation to help you understand it. Here’s an example of Spectral where documentation is unavailable for some of its messages:

No contextual information for an issue

Sometimes an issue’s message alone cannot convey enough information, especially when it is important to understand “how” that particular issue originated in the first place. None of the existing tools provide any extra information along with its messages.

No support for auto-fixing common issues

Several common issues (e.g. inline schemas) often just need simple removal or relocation of certain components in the API definition. Auto-fixing can in such cases greatly reduce the time it takes to bring the API definition to the final shape. Unfortunately, existing tools still lack advanced features like these.

Lack of merge-aware validation

API providers looking to release their microservices as a single unified service for consumers require merging their API definitions into one. Ensuring each API definition is valid before and after the merge is a crucial phase that is not supported by any of the tools out there.

No support for REST formats other than OpenAPI

Most validators like Spectral focus only on OpenAPI as it is the most popular and widely adopted API specification format. However, we’ve observed that other API specification formats are still in use even if in the minority e.g. RAML, Postman Collections, API Blueprint, WADL, etc. These formats are not supported by any of the popular validators out there.

Validation Reimagined - Diving deeper into APIMatic VS Code Extension

1 - Familiar UI

Visual Studio Code is a platform that millions of developers are already comfortable with. APIMatic’s extension has been built with simplicity and efficiency in mind. It offers you dedicated views in the same familiar environment so you can quickly get started. 

2 - Compliance with API specification standards

We enforce all checks marked as mandatory by specification standards like OpenAPI. Such checks are also not configurable. This ensures that your API definition is not only compatible with APIMatic and its products but will work well with other tooling out there as well.

In total, we offer 739 validation rules to check compliance, with 329 rules targeting only OpenAPI definitions.

3 - Out-of-the-box lint checks for code generation and general quality

To ensure smoother SDK generation, DX portal generation, and API specification format transformation, we lint your API definitions against 542 out-of-the-box lint rules with 503 targeting OpenAPI definitions alone. These checks cover all common issues including prevention of inline schemas, ensuring better naming conventions, etc.

You can easily configure the lint process as per needs e.g. you can skip certain rules or even entire rulesets, override the default severity of the rules, and even add custom lint rules.

4 - Support for auto-fixing common issues

This being one of the unique offerings, our auto-fix feature in the extension lets you remove some pesky issues with just a few clicks:

As I mentioned earlier, OpenAPI and other formats aren’t designed for code generation. One of the most common issues we see because of this is an abundance of inline anonymous schemas in API definitions that negatively impact SDK and DX portal generation. Most users we encounter who have such definitions are not always familiar with ways to tackle them efficiently. With auto-fixing, we aim to ease their workload by handling such fixes directly in their files, ensuring accuracy and preventing additional issues. This way they can focus on what matters.

5 - Richer validation experience

In addition to the basic validation support of showing messages in the Editor and Problems view, our extension also provides dedicated views that enhance your validation experience. These views offer improved issue comprehension and quicker access to the information you need, enabling you to address issues with greater efficiency.

Validation Summary View - Get a birds-eye view of all issues

This is a view that shows a complete overview of the validation status of your workspace. 

From here you can:

1. Navigate easily through all validation messages which are grouped intelligently based on severity and whether they are validation or linting messages. Inside these groups, all messages targeting the same issue are grouped, aiding you in addressing all instances of the same issue before moving on to the next. This helps improve the overall efficiency.
2. Generate reports in multiple formats (PDF, HTML, Markdown, JSON) for your external stakeholders.
3. View an overall score of your API workspace which roughly predicts how good or bad the output that you generate from this API definition is going to be.

Current Position Issues View - See in-depth context for all issues you are currently working with

See the in-depth context for all issues you are currently working with.

This view helps show more context for all issues applicable at the current cursor position in the Editor. The information shown in this view includes:

1. Issue message.
2. Severity of issue.
3. The exact location of the issue in the file with the complete line number and position range.
4. A breadcrumb or JSON reference path to the component.
5. Key-value pairs containing contextual metadata to help understand how and why the issue originated.
6. A reference call tree that shows a nested list of components referencing the current component to help understand how the issue originated.

Learn More View - Understand what an issue means and its resolution

Developers are all too familiar with issues that leave them scratching their heads in confusion. We understand that time is precious so we allow you to view details of an issue from within the extension in the Learn More view:

This includes a detailed description of the issue to help you understand what the issue means and why it occurred as well as hints that can be followed for resolving it. We also list down all relevant external links that can be used to learn more about the issue if needed and much more.

6 - Merge-aware validation

APIMatic supports merging multiple API definitions. To ensure a successful merge, it is required that each API definition involved is valid before and after the merge. This is a multi-layer validation process and is supported by our VS Code extension as well.

7 - Multiple API specification formats supported

The extension not only supports OpenAPI definitions but also has basic validation support for other API description formats including RAML, API Blueprint, WADL, WSDL, Postman Collections, Insomnia, HAR, etc.

8 - Ability to transform API specification format

The extension comes with built-in support for API Transformer allowing you to effortlessly convert your API workspace to your chosen output format. For instance, you can convert from OpenAPI to Postman and more.

9 - Better support for APIMatic users

If you are already an APIMatic user, we let you build your API definition from within the extension to check if the API can be successfully exported into APIMatic. Once the API definition is ready, you can easily export it to your APIMatic Dashboard for SDK/DX portal generation without needing to leave the VS Code extension. The extension offers minimal version management as well by letting you replace an existing version or add new versions to the same API group entity.

To configure APIMatic processes, you can easily add an APIMatic Metadata file with just a few clicks:

We support validating all APIMatic-specific files including custom rulesets, APIMatic Metadata files, etc. so you can avoid any common mistakes.

What’s next?

The VS Code extension is currently available in preview mode for our APIMatic users. We welcome you to try it out now:

You can learn more about each of the extension features here and share any feedback.

Anticipated future changes include, but are not limited to:

1. Support for generating SDKs in one or more languages from within the extension.
2. Support for publishing a DX portal from within the extension.
3. Improvements to stability.