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