You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 eitherfilePath or description to specify the new contents of the relevant description field.
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.
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
ordescription
to specify the new contents of the relevant description field.Info
info-description-override
Current example:
Also add support for:
Tag
tag-description-override
Current example:
Change to:
And add support for markdown as an alternative:
Operation
operation-description-override
Current usage example:
Update to the following syntax for filenames:
And add support for markdown:
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.
The text was updated successfully, but these errors were encountered: