mermade/openapi-lint-vscode

OpenAPI 2.0/3.0.x intellisense, validator, linter, converter and resolver extension for Visual Studio Code

openapi-lint README

This extension can be used to validate and lint OpenAPI 3.0.x documents, and convert between OpenAPI 2.0 and 3.0.0. It provides 11 Visual Studio Code commands:

• OpenAPI Validate - which fully validates your OpenAPI document against the specification
• OpenAPI Lint - which additionally applies a lightly-opinionated set of best-practices
• OpenAPI Resolve and Validate - which pulls in external $refs before validating
• OpenAPI Resolve and Lint - which pulls in external $refs before linting
• OpenAPI Resolve (Bundle) - which resolves external $refs to a new window
• OpenAPI 2.0 to 3.0.0 (YAML) - which converts the current OpenAPI 2.0 document to 3.0.0 in YAML
• OpenAPI 2.0 to 3.0.0 (JSON) - which converts the current OpenAPI 2.0 document to 3.0.0 in JSON
• OpenAPI 2.0 to 3.0.0 (YAML/Resolved) - like the above but resolving external $refs
• OpenAPI 2.0 to 3.0.0 (JSON/Resolved) - like the above but resolving external $refs
• OpenAPI to JSON - which simply translates the current document to JSON
• OpenAPI to YAML - which simply translates the current document to YAML

The validator enforces semantic restrictions which cannot be expressed by the JSON Schema which drives the intellisense features, so it will pick up on many more errors.

The linter applies a lightly opinionated set of 'best practices' to your API document, making it complete and comprehensive, as opposed to merely minimally valid.

The default linter rules are documented here. The linter DSL rules format is also documented.

Features

• Validation using oas-validator from OAS-Kit
• Linting using oas-linter also from OAS-Kit
• Resolution using oas-resolver also from OAS-Kit
• Conversion using swagger2openapi also from OAS-Kit
• OAS v3 intellisense for files named *openapi.json, *openapi.yaml, *openapi.yml, *oas3.json, *oas3.yaml, *oas3.yml
• OAS v2 intellisense for files named *swagger.json, *swagger.yaml, *swagger.yml, *oas2.json, *oas2.yaml, *oas2.yml
• Conversion between JSON and YAML
• Snippets (minimal valid openapi/swagger JSON and YAML documents)
• AsyncAPI v2.0.x intellisense for files named *asyncapi.json, *asyncapi.yaml, *asyncapi.yml
• AsyncAPI v1.2.x intellisense for files named *asyncapi1.json, *asyncapi1.yaml, *asyncapi1.yml

Coming soon

• More snippets
• Integration with APIs.guru OpenAPI directory
• Integration with APIs.guru AsyncAPI directory
• Extract default linter rules to new tab to allow saving as overrides

Screenshots

Requirements

The extension should work as-is

Extension Settings

The onSaveAction can be set to one of none, validate, resolveAndValidate (the default), lint or resolveAndLint.

Known Issues

• Jump-to-error functionality not implemented yet (all show as line 1)
• No way to override/amend linter rules yet

Credits

• Icon based upon Icons8

Release Notes

See the CHANGELOG

openapi-lint-vscode's Issues

Incorrectly Flags Elements

It seems this isn't recognizing properties that are OpenAPI 3.0. Please see the attached screenshot. For the openapi, servers and components properties it says, "Unexpected property openapi" or "Unexpected property servers", etc. do I need to turn on OpenAPI 3.0 in the settings or somewhere? HELP!!

multiple openapi.yaml files show errors

Hi,

I have my spec spread out across multiple *.oas3.yaml files. (e.g. root.oas3.yaml and definitions.oas3.yaml) that use the $ref.

If i "resolve and validate" the root file, I receive a notification that the file is valid.

However, if i go into definitions.oas3.yaml, I see red underlines all over the place. For example "Unexpected property ErrorResponse" among others.

How can we let the extension know that this is part of a larger file structure and not show errors when they aren't really errors.

thanks,
jas

Doesn't work offline

Are there plans to allow it to work offline?

Not working with asyncapi file

It's not working with asyncapi file.
File name: moch-schema.yaml (also tried with asyncapi.yaml, same error)
Command used: OpenAPI Lint
Version used: 1.2.0

Linting/Validation does not default to "resolve"

When you have a OAS3 document with references, the linter/validator throws errors like "component name invalid"

If you manually run "resolve and validate" it reports no errors.

Is there an actual reason to NOT resolve references if present?

Is there any way to make resolve & validate the default?

Swagger 2.0 in openapi.yml validates against the incorrect spec

We use libraries which require us to use Swagger 2.0. If I call the file swagger.yml it's ok, but if I call the file openapi.yml it appears to be validating against a version other than 2.0. We'd prefer to standardise the filename of our specs to openapi.yml, but it's causing issues when trying to use this great extension.

I have swagger: "2.0" as the first line of the spec, so I'd hope it would be detect this and validate using the correct spec.

Linter crashes with missing range

Problem description

I am not sure why it fails, because it only failed like this on some machines, and from what I can see the setup was identical. However, this error occured on all our work laptops, not sure why it fails on only some machines yet...

Workaround

I "fixed" it and verifies that the plugin runs when I replace
the https://github.com/Mermade/openapi-lint-vscode/blob/master/extension.js#L147 and https://github.com/Mermade/openapi-lint-vscode/blob/master/extension.js#L194

            let range; // TODO 

with

            let p1 = new vscode.Position(0,0);
            let p2 = new vscode.Position(0,0);
            let range = new vscode.Range(p1,p2); 

but I want to dig a little more into it before submitting a PR. When it fails, it is already inside an exception handler so there are no errors visible to the in VS Code, the plugin just does not work. This "fix" made it work again by printing the errors on position 0, I guess a better fix is to actually try to make the range either the error or the entire document...

Release version 1.3.0

I can see there are new features on master is it possible to release them?

Extension causes high cpu load

• Issue Type: Performance

• Extension Name: openapi-lint

• Extension Version: 1.2.0
  mermade.openapi-lint-unresponsive.cpuprofile.txt

• OS Version: Windows_NT x64 10.0.19041

• VSCode version: 1.49.0

mermade.openapi-lint-unresponsive.cpuprofile.txt

Find more details here: https://github.com/microsoft/vscode/wiki/Explain-extension-causes-high-cpu-load

OpenApi 3.x validation error when "servers" object is present

When adding the servers section with a basic object with only the url mandatory property the validation fails stating that the url property is expected.
This can be reproduced with the OpenApi 3.x Jamal samples

Remove or replace "*" in activationEvents

Problem
Currently, this extension runs on any project, even if that project doesn't use openapi. This unnecessarily adds ~950ms to activation time in some of my larger projects, even though they don't use openapi.

Solution
I know this extension contributes validation schemas and has some commands, but I'm not sure of the full scope of what it does.
If this extension doesn't do anything beyond the validation schemas and commands, I believe the "*" event in package.json's acitvationEvents can be removed entirely.
Otherwise, it could be replaced with specific events, similar to "workspaceContains:**/*swagger.json".

License object is incorrectly requiring license url.

According to https://swagger.io/specification/#licenseObject the url key is not required. However, the linting is saying my document is not valid without it.

Filename prefixes

Please consider making this extension work with filenames that have prefixes too. E.g, instead of just "openapi.yaml", also work with "anything.openapi.yaml".

Validate on save

Currently when I want to validate my openapi.yaml file I have to go through the command palette. It would be good if it would do this automatically, either as I type or on save. Is this possible?

better error output in case the yaml could not be parsed

For validate (or lint) actions:
Currently outputs no information to the user. Extension logs are empty. only in the developer view there is a warning and even that only contains the message, not the location/stack.

        vscode.window.showErrorMessage('Could not parse OpenAPI document as JSON or YAML!');
        console.warn(ex.message);

Maybe at least log the complete error?

            let error = new vscode.Diagnostic(range, ex.message, vscode.DiagnosticSeverity.Error);
            error.source = 'openapi-lint';
            diagnostics.push(error);

Interestingly enough for translate actions (in the code) it looks like it has better error logging. But when trying to execute them I get different errors:

mainThreadExtensionService.ts:65 [[object Object]]Cannot read property 'openapi' of undefined
$onExtensionRuntimeError @ host.ts:10
_doInvokeHandler @ rpcProtocol.ts:365
_invokeHandler @ rpcProtocol.ts:365
_receiveRequest @ rpcProtocol.ts:306
_receiveOneMessage @ rpcProtocol.ts:174
(anonymous) @ rpcProtocol.ts:105
fire @ event.ts:584
fire @ ipc.net.ts:431
_receiveMessage @ ipc.net.ts:764
(anonymous) @ ipc.net.ts:624
fire @ event.ts:584
acceptChunk @ ipc.net.ts:174
(anonymous) @ ipc.net.ts:174
t @ ipc.net.ts:900
emit @ events.js:223
addChunk @ _stream_readable.js:309
readableAddChunk @ _stream_readable.js:290
Readable.push @ _stream_readable.js:224
onStreamRead @ internal/stream_base_commons.js:181
mainThreadExtensionService.ts:66 TypeError: Cannot read property 'openapi' of undefined
	at path\.vscode\extensions\mermade.openapi-lint-1.2.0\extension.js:23:99
	at path\.vscode\extensions\mermade.openapi-lint-1.2.0\node_modules\call-me-maybe\index.js:13:28
	at processTicksAndRejections (internal/process/task_queues.js:76:11)

$ref to adjacent_file object in #/components/parameters block not resolving

Loving the plugin! making lightweight of a new complex spec - but run into something you might not have caught yet.

I have references to both schema and parameter objects in an adjacent file.

If the reference is to adjacent_file.yaml#/components/schemas/schemaObject the link does resolve

If the reference is to adjacent_file.yaml#/components/parameters/schemaObject the link does not resolve

I wonder if the plugin is only built to support the schemas block? I haven't tried the other available components sections: https://swagger.io/docs/specification/components/.

Thanks,
Craig

On validate/lint errors the plugin crashes

if you run Lint, Validate, etc commands and there are any validation/lint errors the plugin crashes with "range" being undefined

pointing to this line of code https://github.com/Mermade/openapi-lint-vscode/blob/v1.2.0/extension.js#L148

OS: MacOS 10.15.6

VSCode:

Version: 1.49.2
Commit: e5e9e69aed6e1984f7499b7af85b3d05f9a6883a
Date: 2020-09-24T16:23:52.277Z (6 days ago)
Electron: 9.2.1
Chrome: 83.0.4103.122
Node.js: 12.14.1
V8: 8.3.110.13-electron.0
OS: Darwin x64 19.6.0

Plugin: 1.2.0

Problem: String is not a URI: [UriError]: Scheme is missing

I'm editing an OpenAPI 3.0 spec in vscode and I believe that this extension is the source of validation problems. I've got several instances where I use $ref to reference a schema, but vscode reports this error:

              schema:
                $ref: '#/components/schemas/Account'

String is not a URI: [UriError]: Scheme is missing: {scheme: "", authority: "", path: "", query: "", fragment: "/components/schemas/Account"}

Any ideas on how to fix this?

Configurable names for OAS v3/v2 intellisense for files

As of today, all files should follow these naming conventions in order to have IntelliSense:

• OAS v3 intellisense for files named *openapi.json, *openapi.yaml, *openapi.yml, *oas3.json, *oas3.yaml, *oas3.yml
• OAS v2 intellisense for files named *swagger.json, *swagger.yaml, *swagger.yml, *oas2.json, *oas2.yaml, *oas2.yml

Would be good to be able to configure the filename patterns.

Validation, linting and conversion with external $ref resolution

Is there still any development on this plug-in? Is there any way to contribute efficiently?

Enhancement: Validation & linting commands should integrate with the VSCode "problems" panel

At the moment, when I perform OpenAPI validation or linting against a YAML document, errors are shown in the pop-up dialog in the bottom-right of VSCode. These pop-up notifications should be reserved for important notifications, not general use of the editor.

Instead of displaying errors as pop-ups, the errors / warnings from the OpenAPI extension should be shown in the Problems panel in VSCode.

As an example, see the screenshot below, which shows "problems" with a couple of Python files.

Cheers,
Trevor Sullivan

Unable to get intellisense unless rename to oas2.yaml

Hi!

Thanks for this extension. I like how it is integrated in visual studio code.

But when I install it, I do not get these working:

• autocomplete as I type does not work as expected. For example, for /definitions/Acme/properties/field1, for "type" I would expect choices like array, string, ...
• syntax highlighting when typing string1 instead of string, it does not show error

However, the menus starting with "OpenAPI" are available when typing F1.

Until I realized that the filename is not the one expected by openapi-lint-vscode.

I tried renaming it from open-api.yaml to openapi.yaml. But now it would complain about my v2.0 version (example: first line start with swagger: "2.0" and gives Missing property "openapi").

Until I rename it to oas2.yaml. Works like a charm!

Any plan to configure that ?

Thanks

Reference path containing spaces can not be opened

Hello everybody

When I try to run "OpenAPI Resolve and lint" on my OpenAPI 3 spec I get a "no such file or directory" error:

Your OpenAPI document is not valid :( 
#/ 
ENOENT: no such file or directory, open 'c:\Users\fasi\Documents\Idea%20Projects\myProject\web_api_gateway\src\main\resources\openapi\AssessmentConfiguration.yaml'. 

The "offending" code snipped is:

responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: './AssessmentConfiguration.yaml#/components/schemas/AssessmentConfiguration'

Like you can see my files are checked-in into a InteliJ IDEA Project, which usually reside in "Idea Projects". I moved all the files to a dir called "tmp" in my home dir and the refs could be resolved no problem. I suspect that the space causes a hiccup when loading the file.

As a temporary work around I moved my source to a new directory containing no spaces.

Information about my system:

• openapi-lint: 1.0.1
• VS code: 1.3.1.1
• Electron: 3.1.2
• Node.js: 10.2.0
• OS: Windows 10.0.16299

Thanks for making this plugin available and maintaining it :-)

references that contain ~0 or ~1 tokens fail lint

See upstream report: Mermade/oas-kit#222

Parsing and linting inline OpenAPI documentation

Hi

Firstly, thank you for the effort and making this plugin available.
We hope to be able to use this plugin to help with documenting our projects.

We prefer writing inline comments right next to the elements (endpoints, schemas etc.) for our work.
Is there a way to enable the linter to parse and lint the inline comments?

Not respecting optional properties

openapi: 3.0.1
For example, I get an error when I don't include the email property in the contact object.