Handling extensions using libopenapi

Using OpenAPI vendor extensions, both simple and complex

OpenAPI extensions (also known as vendor extensions) are properties with a prefix of x- that can be added to many OpenAPI objects throughout the OpenAPI specification.

Both high-level and low-level models support extensions and are available on both via the Extensions property available on all models that support it.

Extensions can be anything! This means there could be a scalar value like a string, or it could be a highly complex, deeply nested object. When we don’t know what’s in the can, its safest to not assume anything.

High level models

It’s pretty simple, all high-level models have the signature:

type SomeHighLevelOpenAPIObject struct {
  Extensions *orderedmap.Map[string, *yaml.Node] // <-- all compatible high level
                                                 //     objects have this extension 
                                                 //     signature.

Low level models

All low-level models have the signature:

type SomeLowLevelOpenAPIObject struct {
  // all compatible low-level objects have this extension signature.
  Extensions *orderedmap.Map[low.KeyReference[string]]low.ValueReference[*yaml.Node] 

Extensions can be anything, so the library simply bubbles up the raw yaml.Node pointer. You’re free to do what you want with it from this point. Marshal it into what ever data shape you need.