External $ref in components.parameters resolves to malformed high-level model

[sanekkurt]

Hello. Thanks for the wonderful library!

I've been using v0.16.4 for a long time, but upgrading to v0.37.2 broke my code.

When a parameter in components.parameters references an external file via a $ref, the resulting high-level model in Go is malformed. Instead of correctly resolving the reference and populating the parameter's fields (name, in, etc.), nothing is resolved (and, moreover, some obscure structures are placed in examples and content fields)

Related to #501 as it points to essentially the same problem, however the fix was implemented only for bundling.

Steps to Reproduce

1. Create following files:

openapi.yaml:

openapi: 3.1.0

components:
  parameters:
    foo:
      $ref: "./list.yaml#/foo"
    bar:
      in: query
      name: bar
      schema:
        type: integer
      required: false

list.yaml:

foo:
  name: SomeName
  in: path
  required: true
  schema:
    type: string

2. Load spec, build document model:

package main

import (
    "encoding/json"
    "os"
    "path"

    "github.com/pb33f/libopenapi"
    "github.com/pb33f/libopenapi/datamodel"
)

func main() {
    filePath := "./openapi.yaml"

    config := &datamodel.DocumentConfiguration{
        AllowFileReferences:     true,
        ExtractRefsSequentially: true,
        BasePath:                path.Dir(filePath),
    }

    b, err := os.ReadFile(filePath)
    if err != nil {
        panic(err)
    }

    doc, err := libopenapi.NewDocumentWithConfiguration(b, config)
    if err != nil {
        panic(err)
    }

    v3Model, err := doc.BuildV3Model()
    if err != nil {
        panic(err)
    }

    data, _ := json.MarshalIndent(v3Model, "", " ")
    println(string(data))
}

Expected Behaviour

The parameters section in Model.Components.Parameters should contain a correctly resolved foo parameter

Actual Behaviour

The foo parameter is malformed

...
   "parameters": {
    "foo": {
     "schema": {},
     "examples": {
      "name": {},
      "in": {},
      "required": {},
      "schema": {}
     },
     "content": {
      "name": {
       "examples": {},
       "encoding": {}
      },
      "in": {
       "examples": {},
       "encoding": {}
      },
      "required": {
       "examples": {},
       "encoding": {}
      },
      "schema": {
       "examples": {},
       "encoding": {}
      }
     }
    },
    "bar": {
     "name": "bar",
     "in": "query",
     "required": false,
     "schema": {},
     "examples": {},
     "content": {}
    }
   },
...

The same issue also affects the filling of Response objects when they reference external files via $ref.

Used environment:

• go version 1.26.3
• libopenapi version v0.37.2

References

A complete example for reproduction is available in the repository: https://github.com/sanekkurt/libopenapi-mre

[daveshanley]

Hello, I will look into this, but thats a pretty huge jump in versions to be honest, many many things have changed since then. I will let you know what I find.

[sanekkurt]

Thanks for your response! I've actually gone ahead and fixed all the other breaking changes in my code. This behavior is now the only thing left preventing me from upgrading to the new version. Everything else works perfectly.

I tried the following workaround:

for pair := doc.Model.Components.Parameters.Oldest(); pair != nil; pair = pair.Next() {
	param := pair.Value
	nameInSpec := pair.Key
	low := param.GoLow()
	if low.IsReference() {
		res, err := high.ResolveExternalRef(low, buildLowParameter, highv3.NewParameter)
		if err != nil {
			panic(err)
		}
		param = res.High
	}
	// param - it will be correct
}

func buildLowParameter(node *yaml.Node, idx *index.SpecIndex) (*lowv3.Parameter, error) {
	var param lowv3.Parameter
	_ = low.BuildModel(node, &param)
	if err := param.Build(context.Background(), nil, node, idx); err != nil {
		return nil, err
	}
	return &param, nil
}

After this, the parameter was populated correctly and my entire code worked successfully. But I'm not sure if this is the right solution.

[daveshanley]

This has been fixed in v0.37.3. Your work around code is no longer required. This was a genuine gap in the codebase.