How to use the Redocly OpenAPI VS Code extension
The Redocly OpenAPI VS Code extension helps you create and update OpenAPI documents.
To start using it, either create a new OpenAPI definition or open an existing one in your VS Code editor.
Default OpenAPI template
If this is your first time working with OpenAPI definitions, you can use our default template to get started.
Create an empty YAML file and open the Cursor context panel. In the panel, select Add template. The extension automatically populates your empty YAML file. Save the changes to the file, and now you have a fully functional OpenAPI definition. You can make changes to it to test the extension, to learn more about the OpenAPI structure, or to design your own API.
OpenAPI structure autocompletion
The extension provides a guided approach to OpenAPI authoring with the autocomplete feature.
To make use of this feature, create a new, empty YAML file.
As you start typing
openapi at the top of the file, the extension will automatically offer suggestions for OpenAPI definition elements according to the specification.
Select a suggestion from the list. The extension will automatically generate the fields supported by the selected OpenAPI section. You can then add your values for each of the fields.
Starting with version 0.2.0, the extension supports value autocompletion for references (
To use this feature, your OpenAPI document must have
components with a proper type defined. For example, the extension will only suggest values for
requestBody if you have
components defined in
requestBodies. Similarly, it will only suggest values from
$ref fields inside
default fields will suggest values you have previously defined in
enum on the same level.
The extension will also show suggested values for all other fields that have a predefined set of values according to the OpenAPI specification (like
required, which has
boolean type; or
type, which must be one of
array | object | number) and that are supported by Redocly CLI.
Dynamic OpenAPI validation
The extension continuously validates the OpenAPI definition you're working on.
Depending on the rules you've added to your
.redocly.yaml file, the extension will warn you about the following issues:
- incorrect type usage
- wrong paths to referenced files
- missing or undefined fields and sections
- and more
Here are some examples illustrating different types of issues and how Redocly OpenAPI points them out.
Missing fields and sections
Wrong path to referenced file
When you use references in your OpenAPI definition, the extension will validate them and warn you if they are incorrect (for example, if the path to a schema in a separate file is incorrect).
Right-click on any
$ref value to access additional navigation options: Go to Definition and Peek.
Selecting Go to Definition opens the referenced item in a new VS Code tab (if it's a separate file) or takes you directly to the section where it's defined (if it's in the same file).
Selecting Peek > Peek definition opens an inline preview of the referenced item within the current VS Code tab.