{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-to-use-the-redocly-openapi-vs-code-extension","__idx":0},"children":["How to use the Redocly OpenAPI VS Code extension"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Redocly OpenAPI VS Code extension helps you create and update OpenAPI documents."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To start using it, either create a new OpenAPI definition or open an existing one in your VS Code editor."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"default-openapi-template","__idx":1},"children":["Default OpenAPI template"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If this is your first time working with OpenAPI definitions, you can use our default template to get started."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create an empty YAML file and open the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Cursor context"]}," panel."," ","In the panel, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://redocly.com/images/vscode/redocly-vscode-default-template.gif","alt":"Adding the default OpenAPI template"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"openapi-structure-autocompletion","__idx":2},"children":["OpenAPI structure autocompletion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi"]}," at the top of the file, the extension will automatically offer suggestions for OpenAPI definition elements ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/OAI/OpenAPI-Specification"},"children":["according to the specification"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://redocly.com/images/vscode/openapi-vscode-author.gif","alt":"Autocompletion"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"value-autocompletion","__idx":3},"children":["Value autocompletion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Starting with version 0.2.0, the extension supports value autocompletion for references (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," fields)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use this feature, your OpenAPI document must have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]}," with a proper type defined. For example, the extension will only suggest values for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestBody"]}," if you have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]}," defined in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestBodies"]},". Similarly, it will only suggest values from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schemas"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," fields inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://redocly.com/images/vscode/openapi-vscode-reference-completion.gif","alt":"References completion"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Autocompletion for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["example"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["default"]}," fields will suggest values you have previously defined in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enum"]}," on the same level."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://redocly.com/images/vscode/openapi-vscode-example-default-completion.gif","alt":"Example and Default completion"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The extension will also show suggested values for all other fields that have a predefined set of values according to the OpenAPI specification (like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["required"]},", which has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}," type; or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", which must be one of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["array | object | number"]},") and that are supported by ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"../cli"},"children":["Redocly CLI"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://redocly.com/images/vscode/openapi-vscode-enum-boolean-completion.gif","alt":"Value completion"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"dynamic-openapi-validation","__idx":4},"children":["Dynamic OpenAPI validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The extension continuously validates the OpenAPI definition you're working on."," ","Depending on the rules you've added to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," file, the extension will warn you about the following issues:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["indentation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["incorrect type usage"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wrong paths to referenced files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["missing or undefined fields and sections"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["and more"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here are some examples illustrating different types of issues and how Redocly OpenAPI points them out."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Missing fields and sections"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/openapi-vscode-missing-section-418baf50cb70b87b.png","alt":"Redocly OpenAPI warning for the servers section"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/openapi-vscode-required-fields-4a617e9735e74c44.png","alt":"Redocly OpenAPI warning for fields in the operation object"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Undefined sections"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/openapi-vscode-security-scheme-adaa51676cad51ae.png","alt":"Redocly OpenAPI warning for undefined security scheme"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Type usage"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/openapi-vscode-type-fab13ccdaf03574f.png","alt":"Redocly OpenAPI warning about allowed types"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Wrong path to referenced file"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/openapi-vscode-incorrect-reference-d1db70b050b2a9ec.png","alt":"Redocly OpenAPI warning about a referenced file not found"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-navigation","__idx":5},"children":["Quick navigation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Right-click on any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," value to access additional navigation options: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Go to Definition"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Peek"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Selecting ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Selecting ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Peek > Peek definition"]}," opens an inline preview of the referenced item within the current VS Code tab."]}]},"frontmatter":{},"tagList":[],"title":"How to use the Redocly OpenAPI VS Code extension","lastModified":"2025-05-28T16:01:32.000Z"}