Update syntax for decorators to support markdown as well as file paths

[lornajane]

Our update-a-description decorators expect the user to put the markdown into a separate file, and then refer to the file from the decorator. This is a decent use case, but can be overkill when just a couple of lines of content is needed, such as to update the description for a single operation. In comparison with overlays, the decorators look more complicated, when they're really not.

I propose we update the syntax for the *-description-override decorators, to make them consistent with one another, and to add the option of in-config markdown as well as the existing external-file markdown.

In all cases, the user can use either filePath or description to specify the new contents of the relevant description field.

Info info-description-override

Current example:

info-description-override:
  filePath: ./my-custom-description.md

Also add support for:

info-description-override:
  description: >-
    Words or markdown here, [CommonMark format](https://commonmark.org/) is supported.

Tag tag-description-override

Current example:

tag-description-override:
  tagNames:
    planet: ./my-planet-description.md
    star: ./my-star-description.md

Change to:

tag-description-override:
  tagNames:
    planet:
      filePath: ./my-planet-description.md
    star:
      filePath: ./my-star-description.md

And add support for markdown as an alternative:

tag-description-override:
  tagNames:
    planet:
      description: A very interesting planet, with a charming orbit.
    star:
      description: Solo primary dwarf.

Operation operation-description-override

Current usage example:

operation-description-override:
  operationIds:
    updateEvent: ./my-custom-description.md
    createEvent: ./add-an-event.md

Update to the following syntax for filenames:

operation-description-override:
  operationIds:
    updateEvent:
      filePath: ./my-custom-description.md
    createEvent:
      filePath: ./add-an-event.md

And add support for markdown:

operation-description-override:
  operationIds:
    updateEvent:
      description: Change the details of an existing event.
    createEvent:
      description: Add an event to the upcoming events listing.

Alternatives considered

Do nothing; users are adopting overlays. However I do think the descriptions are an 80% use case and the decorators are a nicer experience for doing those updates.

We should also consider doing https://redocly.com/docs/cli/decorators/media-type-examples-override/ as a followup.