What is the expected way to load extensions as complex types?

[danielgtaylor]

I have an extension x-cli-config that enables client auto-configuration given an Open API 3 document (think stuff like security set up, additional headers to always send, and an ability to prompt users for information). This configuration object is somewhat complex with a number of nested fields/objects.

It looks like libopenapi loads extensions as interface{} while kin-openapi loaded them as json.RawMessage. You can unmarshal the raw message into your struct fairly easily, but there is no stdlib way to unmarshal from already existing Go maps. For now I'm trying to use mapstructure to do something similar going from interface{} -> my struct, like so:

var config *autoConfig

if err := mapstructure.Decode(model.Extensions["x-cli-config"], &config); err != nil {
  fmt.Fprintf(os.Stderr, "Unable to unmarshal x-cli-config: %v", err)
  return
}

Is this the right way to do it? Is there some other way you expect users of the library to load their extensions? Some kind of way to register an extension with a type before loading might be nice, and then during loading it could instantiate that type, though maybe that's overkill for this library.

Part of danielgtaylor/restish#115.

[daveshanley]

I left this open-ended to see how people would prefer to consume these extensions. This use case has come up in another project as well.

There are two ways we can currently do this. You're already using the first method (which is fine if you already have the dependency in the project), or you can use GoLow() and extract the *yaml.Node object that represents the raw data and serialize that node into a struct using Decode or Encode (https://pkg.go.dev/gopkg.in/yaml.v3#Node.Decode)

I like your idea of 'registering extensions' with a type. It makes a lot of sense. It would be a nice feature to add once the library's core is in place. I'm working on a 'what-changed' feature right now and then validation after that., perhaps this would be a good follow-up feature. mainly because extensions are so crucial for custom development.

[TristanSpeakEasy]

Can I maybe suggest until a feature targeted at extensions is made, that the current options are documented instead?

[daveshanley]

I'll update the README with a blurb and some examples and add some sample code to the docs.

[daveshanley]

Ok, so I went a step further and created the first step toward a register types function. To begin, there is a new UnpackExtensions function available in the high package of data model.

There is an example available:

https://github.com/pb33f/libopenapi#loading-extensions-using-complex-types

It should make working with complex types and extensions much easier and reduce a lot of code. It should work until a more powerful, auto-magic version of this feature can exist, but that's more work than I have time for right now.

The README has been updated, and the docs with working sample code.

Available in v0.3.2

[daveshanley]

Updated docs are available here:

https://pb33f.io/libopenapi/extensions/

[daveshanley]

Extensions now arrive as *yaml.Node which allows end-users to define what to do with them. libopenapi hands you control to make your own choices.

Closing this as answered.