redocly-cli
redocly-cli copied to clipboard
Update syntax for decorators to support markdown as well as file paths
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.