Redocly Decorators That Inject Content at Bundle Time: Power and Lock-In

Quick answer: A Redocly decorator is a plugin that transforms an OpenAPI document during the bundle step, adding, removing, or rewriting content before it is published. That power is useful for enforcing consistency and injecting generated sections, but it means the bundle no longer reflects the source document alone, and the transform only runs inside that toolchain. Keep decorators small and transparent, keep the source document independently valid, and treat every injected section as a dependency that could block a migration.

What a decorator actually does

Redocly separates authoring from bundling. The source OpenAPI document stays in the repository, and at bundle time a decorator walks the document tree and mutates it: adding a header to every operation, injecting a generated description, or removing an internal field for a public build. The transform is deterministic and reviewable, but it introduces a gap between what you wrote and what ships. If someone reads the published bundle and looks for the same text in the source, it will not be there, because the decorator added it.

Capability	Benefit	Lock-in cost
Inject content at bundle time	Consistent generated sections	Output depends on the plugin
Rewrite or remove fields	One source, multiple targets	Other tools do not apply the rule
Enforce organization-wide patterns	Uniform operations	Logic lives outside the spec

A simple decorator

Here is the shape of a decorator that adds a standard header parameter to every operation. The logic lives in a plugin rather than being repeated by hand in the document.

Every operation now carries the parameter in the published bundle, even though no author wrote it. That guarantees consistency, but it also means a build that does not run the decorator will silently omit the header.

Where the power becomes a problem

The risk grows when decorators absorb substantive content decisions rather than mechanical cleanup. If a decorator injects descriptions or rewrites request schemas, the source document stops being a complete and trustworthy artifact, and understanding an operation requires reading the plugin too. A migration to another toolchain is then expensive: the content that the decorator was silently producing has to be reconstructed in the source or replaced with equivalent logic.

Keeping the source document valid

A useful discipline is to keep the source document independently valid under a standard linter, with decorators reserved for presentation and target-specific adjustments rather than for making a broken document appear correct. If a decorator is fixing a structural problem, that fix belongs in the source, because otherwise every other tool that reads the document sees the defect. Reserve the bundle-time transform for genuinely repetitive, reversible changes that the document should not carry itself.

Making the transform transparent

Decorators should be few, named for what they do, and covered by tests that assert the exact change in the bundled output. Review the generated bundle as part of the pull request so the injected content is visible rather than assumed, and document which decorators affect which parts of the document. A transform that no one can trace is the dangerous case; a small, tested plugin with a clear purpose is a controlled one.

How an agent mishandles it

An agent that is asked to make the bundle look right often pushes logic into a decorator to avoid editing many operations, which is appropriate for mechanical repetition but wrong for content that belongs in the source. Ask it to classify each change as either a repetitive presentation transform or a substantive fix, and move the latter back into the document. If the agent adds several decorators that mutate the same section, consolidate them: overlapping transforms are hard to reason about and compound the lock-in.

A worked example of a safe versus risky transform

The line between a decorator that earns its keep and one that creates hidden content is clearest with a comparison. A decorator that adds a stable, mechanical header to every operation is safe because the source document remains complete without it and the change is purely repetitive. A decorator that composes a description from other fields or rewrites a schema is risky, because the source no longer tells the whole story and every other tool reads a different document.

When you find a decorator doing the risky kind of work, move the generated content back into the source or make it a clearly separate build artifact rather than pretending it is part of the authored spec.

Testing the bundle and keeping an escape hatch

Snapshot the bundled output for a small set of representative operations so any change in a decorator's behavior is caught in review, and document the purpose of each plugin alongside the configuration. If you ever leave the toolchain, that documentation tells you exactly which mechanical transforms need to be reproduced. Keeping the source document valid on its own is the real escape hatch: the decorators stay optional enhancements rather than load-bearing logic that the spec cannot build without.

Frequently asked questions

What is the difference between a decorator and a lint rule?

A lint rule reports problems and can enforce standards, while a decorator mutates the document during the bundle. A decorator changes the output, so it creates a gap between the source and what is published.

Why are decorators a lock-in concern?

The transform only runs inside the bundling toolchain, so a migration means the injected content must be reconstructed elsewhere. The more substantive the decorators, the more work moves with them.

Should decorators fix structural problems in the spec?

No. Keep the source document independently valid; use decorators for repetitive, presentation-level changes rather than hiding defects that other tools will still see.

How do I keep decorators safe?

Keep them small and named, test the exact bundled output, review the generated bundle, and document which parts of the document each transform affects.

This is part of the Powerduck vs Redocly: OpenAPI Docs and Linting — start there for the full comparison of docs and linting toolchains.