README.md

May 21, 2022 ยท View on GitHub

Demo of decorators to override descriptions

  • info-description-override
  • operation-description-override
  • tag-description-override

Result

Original: https://decorator-overrides-demo.redoc.ly/original v1 (with override decorators): https://decorator-overrides-demo.redoc.ly/v1

Browse around and change the version switch in the left sidebar navigation to see the original and v1 versions.

info-description-override

2021-11-03_18-23-53

tag-description-override

2021-11-03_18-30-53

operation-description-override

2021-11-03_18-32-43

Problem

These built-in decorators solve the age-old problem of not being able to modify the OpenAPI definition at the source. This typically happens for code-generated OpenAPI definitions. Developers can use code annotations to describe the APIs, and then run a command that pulls together an OpenAPI file.

One of the drawbacks is that any edits made to that file will be overwritten the next time the file is generated again.

Technical writers, and other non-developer contributors, don't have access to the source code (or sometimes the code annotations library itself is limited).

Solution

Use decorators to decorate the OpenAPI file. When the original OpenAPI file changes, the decorators run when bundling and update it accordingly.

bundle command + decorator + original OpenAPI file = new OpenAPI file

  1. Add Markdown files with the new descriptions for operations, info, and tags.
  2. Adjust the configuration file (redocly.yaml) (or create one) -- it should have the decorators object. See the redocly.yaml configuration file in this repository for an example.
  3. Run the bundle command: redocly bundle decorators@v1.