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.

[handrews]

Given that this is already in use in the wild, we should probably consider it for 3.2.

Philosophically, I find this kinda meh, but that's pretty much the only argument against it that I can think of and even I don't find that convincing 🙃

I think the main question for 3.2.0 is how much we want to add any new referencing requirements. But "it's already implemented" is pretty compelling evidence that it's not hard.

[lornajane]

I think we should consider how to serve this use case, but I am not in favour of the existing suggested syntax, putting a $ref: somefile.md field where a string should be.

Looking at other ways that this is implemented elsewhere, there's some much nicer description-override functionality in the Speakeasy customisation options: https://www.speakeasy.com/docs/customize-sdks/sdk-docs#per-sdk-comments where an x- extension allows replacing the value (admittedly with another string rather than a ref)

I already had a half-baked idea for doing an x-md-description field in info that would expect a `$ref. Using one of the transform tools to grab the contents of the file and overwrite the description field with it would be a good way to implement that today.

For us to include something like that in the docs, does it become like the License field, a mutually exclusive choice between description or description-file ?