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.
Found an issue or have an idea for improving the extension? Let us know!
Before you start
Be aware that the extension may be affected by some limitations of the VS Code editor.
So far, we have identified these limitations:
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.
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. Now you have a fully functional OpenAPI definition you can use with the extension.
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.
Starting with version
The extension will also show suggested values for all other fields that have a predefined set of values according to the OpenAPI specification (like
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.
Interactive forms and 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.
For supported sections, the Cursor context panel can also display a visual editor where you can change the contents of your API definition through interactive forms.
Depending on the currently selected section of the OpenAPI document, the Cursor context panel may show triple bar ("hamburger") icons to the left of each input field in the visual editor. Use these icons to change the order of fields in the panel. To reorder a field, select the triple bar icon next to it, then drag-and-drop it up or down in the panel.
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.