Unexpected theme/htmlTemplate config warnings in v1.15.0

[javierjulio]

Describe the bug

Since updating @redocly/cli from 1.14.0 to 1.15.0, when running npm test which in turn runs redocly lint, these 2 redocly.yaml warnings are reported unexpectedly:

> redocly lint

[1] redocly.yaml:16:5 at #/theme/openapi/htmlTemplate

Property `htmlTemplate` is not expected here.

14 | theme:
15 |   openapi:
16 |     htmlTemplate: redoc-web/index.html
17 |     theme:
18 |       spacing:

Warning was generated by the configuration spec rule.


[2] redocly.yaml:17:5 at #/theme/openapi/theme

Property `theme` is not expected here.

15 | openapi:
16 |   htmlTemplate: redoc-web/index.html
17 |   theme:
18 |     spacing:
19 |       unit: 5 # CE  # main spacing unit used in autocomputed theme values later

Warning was generated by the configuration spec rule.


⚠️ Your config has 2 warnings.

I don't know what is causing this since reviewing the openapi-starter, which I based the docs off years ago, it's a match. The keys are in the expected place and have valid values. Although if a value say in theme was invalid, I wouldn't expect that warning message.

We encounter the same reported warnings both in CI (GitHub Actions) and locally.

For what it's worth, I had issues previously with the config file reporting warnings when we it was using the features key and that took awhile to be resolved.

This change https://github.com/Redocly/redocly-cli/pull/1495 which was included v1.15.0 could be the cause.

This is my redocly.yaml file:

# See https://redoc.ly/docs/cli/configuration/ for more information.
apis:
  main@v1:
    root: openapi/openapi.yaml
extends:
  - recommended
rules:
  no-unused-components: warn
  info-license: off
  info-license-url: off
  no-invalid-media-type-examples:
    severity: warn
theme:
  openapi:
    htmlTemplate: redoc-web/index.html
    theme:
      spacing:
        unit: 5 # CE  # main spacing unit used in autocomputed theme values later
        sectionHorizontal: 30 # CE  # Horizontal section padding. COMPUTED: spacing.unit * 8
        sectionVertical: 30 # CE  # Horizontal section padding. COMPUTED: spacing.unit * 8
      colors:
        primary:
          main: "#1E88E5"
      typography:
        fontSize: '16px' # CE
        lineHeight: '1.5' # CE
        fontWeightRegular: '400' # CE
        fontWeightBold: '700' # CE
        fontWeightLight: '400' # CE
        fontFamily: '-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif' # CE
        smoothing: 'antialiased' # CE
        optimizeSpeed: true # CE
        headings:
          fontFamily: 'Montserrat, sans-serif' # CE
          fontWeight: '400' # CE
          lineHeight: '1.6em' # CE
      logo:
        gutter: '20px' # logo image padding # CE
      rightPanel:
        # backgroundColor: '#263238' # CE
        width: '50%' # CE
        # textColor: '#ffffff' # CE

To Reproduce

This is reproducible with the openapi-starter library which generates the same warnings and an additional one.

1. Download the openapi-starter https://github.com/Redocly/openapi-starter/archive/refs/heads/main.zip
2. Update the redocly version in package.json to 1.15.0
3. Run npm install
4. Run npm test
5. The theme/htmlTemplate warnings will be reported

Expected behavior

The two warnings should not be reported since the config is valid and those two keys are in the correct location where they should be defined.

Logs

OpenAPI description

Redocly Version(s)

v1.15.0

Node.js Version(s)

v20.10.0

Additional context

[javierjulio]

Looks like it's related to this change https://github.com/Redocly/redocly-cli/pull/1495 that was introduced in v1.15.0

[jmacelroy]

Hello, I came here to report the same issue just now. It also seems to impact generatedCodeSamples which I get in addition to those stated above. I am using a fairly standard redocly.yaml which is from the starter project example.

Let me know if there's info I can add that may help.

[tatomyr]

Hi guys! Sorry for the inconvenience. We're modifying the default configuration format, but you can still safely use your current configuration. You either stay on the v1.14.0 or move the theme/openapi section under features.openapi like the following to avoid warnings:

features.openapi:
  htmlTemplate: redoc-web/index.html
  theme:
    spacing:
      unit: 5 # CE  # main spacing unit used in autocomputed theme values later
      ...

Please let me know if you need any other assistance.

[javierjulio]

@tatomyr no worries and thank you. Sorry, at the time I tried reproducing with openapi-starter but I didn't update the @redocly/cli version. I tried that again with it using the 1.15.0 version and the warnings are reproducible. I wasn't sure based on your message if the team was aware of that or not so just wanted to follow up. I updated the description with the reproduction steps I took. We'll remain on 1.14.0 for now.

[skyegecko]

features.openapi:
  htmlTemplate: redoc-web/index.html
  theme:
    spacing:
      unit: 5 # CE  # main spacing unit used in autocomputed theme values later
      ...

This configuration gives me a deprecation warning:

The 'features.openapi' field is deprecated. Use theme.openapi instead. Read more about this change: https://redocly.com/docs/api-registry/guides/migration-guide-config-file/#changed-properties

The linked document however says that this is what I should be migrating to, and the alternative config offered by the warning doesn't even work. I'm using v1.16.0

I'm brand new to redocly and at the moment I have no idea what I should or shouldn't be using for forward compatibility.

[lornajane]

@dutchgecko thanks for chiming in. Unless you're in our early adopters program, then I suggest you use a 1.14.x version of the CLI tool for now, which should validate correctly for our existing products. If that doesn't help, share your config and I'll take a look?

[skyegecko]

@lornajane Thanks, I'll roll back for now.

[tatomyr]

We moved back the support for the old syntax in the recent versions. There could be some deprecation warnings though. FYI @javierjulio @jmacelroy @skyegecko

[javierjulio]

@tatomyr thank you. What PR(s) completed this and what version is it included in? I haven't updated since the v1.14.0 release.

[tatomyr]

@javierjulio I believe it's in v1.18.1.

[javierjulio]

@tatomyr thank you. I updated to the latest version and I don't see the config warnings anymore.