openapiredocly

Is $ref allowed in info.description in OpenAPI 3.0/3.1 documents?


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?


Solution

  • 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.