allowing $ref in descriptions

[manasesjesus]

Some descriptions can be long or very long. Allowing $ref would be useful to reference an external file with only text, e.g. markdown. It'd be great if info.description and tags.name/description could use it (without IDE validation errors).

[webron]

How would you tell whether the description is a reference or actually the text itself?

[manasesjesus]

Specify it on a new line, like this:

openapi: 3.0.3
info:
  title: AcMe OpenAPI
  description:
    $ref: "markdown/acme-oas.md"

# more stuff here...

- name: Controls
  description:
    $ref: "markdown/controls.md"

It works like a charm; we render a web documentation and also swagger-cli bundle works fine, but the IDE shows error messages like this one: Incorrect type. Expected "string". "yaml-schema: Validation schema for OpenAPI Specification 3.0.X."

[webron]

It works like a charm if it's a JSON Schema document (which in many places its not). But what if those are the actual values of the description and are not meant to be references?

[hkosova]

@webron a literal string $ref: "markdown/controls.md" can be written as

description: >-
  "$ref": "markdown/controls.md"

description: '"$ref": "markdown/controls.md"'   # note the extra quotes around the string

description:
  '"$ref": "markdown/controls.md"'   # note the extra quotes around the string

description: "\"$ref\": \"markdown/controls.md\""

or similar.

This is different from

description:
  $ref: "markdown/controls.md"

which denotes an object with the $ref key.

[ReyhanPatria]

I'd like to upvote this feature request as well

[handrews]

It works like a charm if it's a JSON Schema document (which in many places its not). But what if those are the actual values of the description and are not meant to be references?

JSON Schema only allows $ref in a schema, not for text values like description.

[lornajane]

There are definitely a number of requests for adding more $ref support (I see @handrews has tag to bring these items together).

The request for allowing the markdown fields to refer to externally-stored markdown is a very valid one. Redocly does support exactly the syntax suggested in this issue and one of the big benefits is that the markdown can more easily be linted/spellchecked etc when its in a markdown file than when it's in another data structure. Especially for the description fields that accept markup, this would be a good feature.