Skip to content
Last updated

Migrate to Redocly CLI v2.x from v1.x

Redocly CLI v2 introduces improved architecture and removes deprecated features to make the tool easier to maintain and extend. This guide covers the essential changes you need to make when upgrading from v1.x.

Prerequisites

Node.js version: Update to Node.js 20.19.0+, 22.12.0+, or later.

Breaking changes

Module system migration

The codebase has been rewritten from CommonJS to ES Modules. This affects plugins: update your plugin syntax to use ES Modules, or use the .cjs extension for CommonJS files.

Configuration changes

The only default configuration file name is now redocly.yaml. If you still use the legacy .redocly.yaml, please rename it. You can still use a different file name, but you must explicitly specify it with the --config flag.

Several deprecated configuration options have been removed:

# ❌ Removed - use 'apis' instead
apiDefinitions:
  - openapi.yaml

# ✅ Use this instead
apis:
  main: openapi.yaml
# ❌ Removed - use 'openapi' directly
features.openapi:
  theme:
    colors:
      primary:
        main: '#ff0000'

# ❌ Removed - use 'openapi' directly
theme:
  openapi:
    theme:
      colors:
        primary:
          main: '#ff0000'

# ✅ Use this instead
openapi:
  theme:
    colors:
      primary:
        main: '#ff0000'
# ❌ Removed - use 'rule/' prefix
rules:
  assert/name: error

# ✅ Use this instead
rules:
  rule/name: error

Rule changes

The spec rule has been replaced with struct:

# ❌ Removed
rules:
  spec: error

# ✅ Use this instead
rules:
  struct: error

Or use the new spec ruleset for specification compliance:

extends:
  - spec

Removed rule path-excludes-patterns. Use a configurable rule instead. You may refer to this Cookbook recipe.

Removed rule info-license-url. Use info-license-strict which better complies with the new OpenAPI 3.1 specification.

Configurable rules changes

The undefined assertion has been removed:

# ❌ Removed
rules:
  rule/check-property:
    subject:
      type: Operation
      property: summary
    assertions:
      undefined: false

# ✅ Use this instead
rules:
  rule/check-property:
    subject:
      type: Operation
      property: summary
    assertions:
      defined: true

Platform changes

  • Legacy Registry: Support for the legacy Redocly API Registry has been removed in favor of Reunite.
  • Commands: The preview-docs command has been removed - use preview instead.
  • Labels: The labels field in the apis section has been removed.

New features

Spec ruleset

A new spec ruleset is available that enforces OpenAPI specification compliance:

extends:
  - spec

Duplicate tag detection

The no-duplicated-tag-names rule checks for duplicate tag names in your API description.

JSON schema format validation

Now Redocly CLI supports JSON schema formats:

openapi: 3.1.0
paths:
  /users/{id}:
    get:
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
              examples:
                Correct:
                  value:
                    email: correct@email.com
                Incorrect:
                  value:
                    email: wrong-email # Will fail validation

Migration checklist

  1. Update Node.js to a supported version (20.19.0+, 22.12.0+, or 23+).
  2. Rename configuration file name to redocly.yaml (if it differs).
  3. Replace spec rule with struct.
  4. Update configurable rules to use rule/ prefix instead of assert/.
  5. Replace undefined assertions with defined: true.
  6. Update configuration structure:
    • Replace apiDefinitions with apis
    • Move features.openapi.* to openapi.*
    • Remove labels from apis section
  7. Update plugins to ES Modules syntax or use .cjs extension.
  8. Test your configuration with redocly check-config.

Next steps

 
Next page