Configuration

To use the extension, we recommend you create a configuration file called redocly.yaml and place it in the root directory of your workspace. If the extension detects that this file doesn't exist, it prompts you to create it automatically for the current workspace.

Here's an example of what your directory structure could look like:

├──workspace
│   ├──openapi-definitions
│   │   ├──production.yaml
│   │   └──test.yaml
│   ├──redocly.yaml
│   ├──some-file.txt

The redocly.yaml configuration file defines the criteria for validating OpenAPI definitions.

Add the following example contents to the file and save the changes:

apiDefinitions:
  main: path/to/your-openapi.yaml
  test: path/to/another-openapi.yaml
lint:
  extends:
    - recommended
  rules:
    tag-description: off
    operation-summary: error
    no-unresolved-refs: error
    no-unused-components: error
    operation-2xx-response: error
    operation-operationId: error
    operation-singular-tag: error
    no-enum-type-mismatch: error
    no-identical-paths: error
    no-ambiguous-paths: error

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 redocly.yaml file, you must save it to disk for your changes to apply. To learn more about built-in rules you can use, refer to the Redocly CLI documentation. The configuration reference provides more information on how to configure the tool.

Note that you can add multiple paths to OpenAPI files in the apis object. APIs listed automatically validate by the extension when you open them in VS Code. Changes made to apis are dynamically reflected in the preview panel.