feature(kuma-http-api): add custom overlayer that can deref during overlay

[johncowen]

Adds a smol wrapper around https://github.com/thim81/openapi-format (which is the overlay lib/CLI we are using) to allow us to dereference $refs before the overlay happens.

I decided to add our own custom CLI instead of composing CLI calls using make because I wanted to avoid making lots of intermediate files though the pipeline. This way you have one overlay source file and a single generated OpenAPI spec.

I've made some inline notes to help review, but also note there are a few formatting changes just due to the multiple bits of serializing/deserializing happening as the YAML goes through the pipeline.

Lastly, we can't really merge this as yet as we need the upstream issue resolved - worst case scenario we are going to have to patch or fork the upstream lib - or potentially find another overlay tool/lib that we can use. Leaving in Draft for the moment, but a totally open for review and potential informal approval at this stage 👍

Upstream bugfix is in, I've added a couple of commits on the end of here for the upgrade of openapi-format and then one more make build - packages/kuma-http-api/dist/components/schemas/MeshAccessLogItem_Put_RequestBody.yaml is now how we want it 🎉

[netlify]

✅ Deploy Preview for kuma-gui ready!

Name	Link
🔨 Latest commit	6ee6751
🔍 Latest deploy log	https://app.netlify.com/projects/kuma-gui/deploys/69412a13343ed600082f1b14
😎 Deploy Preview	https://deploy-preview-4420--kuma-gui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[johncowen]

Notes:

[thim81]

@johncowen Don't know the full details of your use-case, but I just wanted to share that eopenapi-format, dereferences the OpenAPI document before processing it.
https://github.com/thim81/openapi-format?tab=readme-ov-file#bundling-the-openapi-document

[johncowen]

Hey @thim81 👋 😄

Don't know the full details of your use-case, but I just wanted to share that eopenapi-format, dereferences the OpenAPI document before processing it.

Gotcha yeah, I've tried various ways whilst sticking to standard tooling/approaches, but I realized that in our very weird case we need to add $refs into the overlay file and then have them all be dereferenced before the overlay happens.

This way we can overlay the targets of $refs in subsequent action: updates in the same overlay without changing the original target of the reference.

As this is a bit non standard overlay functionality I doubt there'll be any support in standard-ish tooling (and there probably shouldn't be)

The PR here adds optional dereferencing to the overlay itself via a YAML tag, so we can choose which $refs get dereferenced before overlaying and which once get dereferenced afterwards (we need both types!)

Anyway, a bit hard to explain our usecase 😅 but thats more or less it.

BTW, thanks for the great tool, super handy! Seems to be the only one that supports OAS Overlay extends out of the box 👍

Anyway, no doubt catch up after the weekend

[schogges]

LGTM so far, left some nits 🙂

[johncowen]

FYI Added this to the desc here:

Upstream bugfix is in, I've added a couple of commits on the end of here for the upgrade of openapi-format and then one more make build - packages/kuma-http-api/dist/components/schemas/MeshAccessLogItem_Put_RequestBody.yaml is now how we want it 🎉

Taking out of draft

Thanks again @thim81 !

[schogges]

👍