2

The Redocly quick start has the following:

info:
  description:
    $ref: ./info-description.md

Running the Redocly CLI behaves correctly with this definition. Likewise running "redocly lint". Visual Studio, however, complains that the value of description must be a string,

Visual Studio error message

and indeed, the specification agrees. The Swagger documentation also notes that $ref is not available just anywhere (but doesn't give very much information on exactly where it is allowed).

It seems unlikely that Redocly, as one of the principal tools in the world of OpenAPI, would violate the standard in its own canonical example of how to use the standard. Is this a problem with Redocly, Visual Studio or something else? If this usage is correct, is there a way to tell Visual Studio to stand down?

Scott Deerwester
  • 3,503
  • 4
  • 33
  • 56
  • Well, that's embarrassing. Hi, I work at Redocly, and I'm going to and make some changes to our example project! (as well as answer your actual question) – Lorna Mitchell Apr 21 '23 at 13:29

1 Answers1

2

You are correct, info.description should be a string - the $ref isn't supported everywhere in the OpenAPI specification, although it's not always clear where it is and isn't supported. Redocly will try to resolve the $ref wherever it is, since it's clear what the user intended. Some other tools do the same - but as you found, not all of them; I think in this case the Visual Studio tool is correct.

Lorna Mitchell
  • 1,819
  • 13
  • 22
  • 1
    Thanks for the quick answer. Logically, I think Redocly got it right. I can't see a logical reason for excluding this here. But the standard is the standard, I suppose. – Scott Deerwester Apr 21 '23 at 13:47
  • 1
    If anyone else runs into this, Redocly now has a rule you can enable to check for not-officially-correct usage of `$ref`. The rule is `spec-strict-refs` and the docs are here: https://redocly.com/docs/cli/rules/spec-strict-refs/ – Lorna Mitchell Jun 12 '23 at 13:50