Support overlays

[scharrier]

We want to be able to apply an overlay to an API definition before it's sent to our servers.

At the CLI level, this means adding an overlay method allowing us to get a new version of our definition after applying the overlay:

bump overlay path/to/definition path/to/overlay --out=path/to/destination

If no--out parameter is provided, stdout is used.

We also want to add a parameter to the deploy command:

bump deploy path/to/definition --overlay=path/to/overlay

Which will apply the overlay to the definition just before deploying it on Bump.sh (nothing written on disk, we apply it "in memory" only)

In a near future (this is not part of this issue), we will also add this as an option to our GitHub action, so the code we write here should be usable outside of the CLI (this can be done later).

Questions:

• how do we handle $ref? is there any way to apply the overlay on external dependencies?
• do we want to allow applying an overlay on a components file? if yes, are there some consequencies?

[paulRbr]

First implementation is available here: #553

[scharrier]

@paulRbr if I'm correct, this implementation doesn't follow the proposed args/options. I could review it, but I think it would be more efficient if I review something that matches the expectations. If you disagree with the proposed options/args, feel free to share your opinion, it was just a first proposal!

Also, would you have some time to answer the small questions at this end of this issue? Thanks a lot! 🙏

[paulRbr]

I think it would be more efficient if I review something that matches the expectations.

Sure think, I'll ping you when I have time to update the initial implemntation

• how do we handle $ref? is there any way to apply the overlay on external dependencies?

With the current implementation, we used an external lib which doesn't apply overlay on references data. It applies overlays on a target jsonpath of the input json/yaml document.

• do we want to allow applying an overlay on a components file? if yes, are there some consequencies?

That's a good question. For now I've limited the possibility to apply an overlay only on a “API document” (a document that looks like an AsyncAPI or OpenAPI). But we can discuss this further. I don't think there's a strong limitation for what you ask as the overlay is basically fetching a JSON path inside a simple JSON/YAML object.

[scharrier]

Thanks for the explanation. Let's talk about this next week, when you had some time to work on it!

[philsturgeon]

This is done! :raised_hands:

[philsturgeon]

This is done! :raised_hands: