Redocly OpenAPI is a Visual Studio Code extension that helps you write, validate, and maintain your OpenAPI documents. It warns about errors in OpenAPI definitions and lets you quickly access referenced schemas or open the files that contain them. The extension works with OpenAPI 2.0 and 3.0 definitions, and has basic support for OpenAPI 3.1.
Before you start
To install the extension in VS Code:
To use the extension, we recommend you create a configuration file called
Here's an example of what your directory structure could look like:
Add the following example contents to the file and save the changes:
This will let you start working with the extension. You can modify the file at any point to control the behavior of the extension. When modifying the
Note that you can add multiple paths to OpenAPI files under
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.
OpenAPI structure autocompletion
To use the extension for OpenAPI authoring, create a new, empty YAML file. As you start typing
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.
Dynamic OpenAPI validation
The extension continuously validates the OpenAPI definition you're working on. Depending on the rules you've added to your
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
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.
Live preview of the API documentation
The Redocly OpenAPI VS Code extension relies on Redocly Reference to generate a preview of the API documentation based on the OpenAPI document you're editing. This lets you see the OpenAPI source and the documentation generated from it side-by-side. When you save a change to your OpenAPI definition, the documentation in the preview panel is automatically updated.
Access the documentation preview in any of the following ways:
Both actions open the Preview panel.
When you have generated your personal API key, paste it into the API key in the Preview panel and select Submit. Documentation previews will be enabled for all your workspaces.
In the tab bar above the panel, select the name of the YAML file for which you want to preview the documentation. If you have defined custom names in the
To customize the documentation preview, add supported Reference configuration options to the
For example, to hide the logo image and change the font size and color, you could add the following:
Remember to save the
To exit the documentation preview, close the Preview panel. You can open it again at any point.
Context-aware help for OpenAPI authoring
To help you write valid, specification-compliant API definitions, the Redocly OpenAPI VS Code extension provides dynamic descriptions of OpenAPI features in the cursor context panel.
Access the cursor context in any of the following ways:
Both actions open the Cursor context panel.
As you place your cursor into different sections of your OpenAPI document, the context-aware descriptions in the panel change to match the exact object or property you're editing.
To exit, close the Cursor context panel. You can open it again at any point.
If you suspect the extension is not working properly, make sure the following conditions are true:
Installation and usage of the extension are subject to the terms and conditions of the Redocly Subscription agreement.