openapi3: serialize Extensions when using $ref (#1131)

Co-authored-by: Ian Rees <ian@ianrees.net>

Author: fenollp

.github/docs/openapi3.txt

@@ -1314,12 +1314,23 @@ func URIMapCache(reader ReadFromURIFunc) ReadFromURIFunc
     documents.
 
 type Ref struct {
-	Ref    string  `json:"$ref" yaml:"$ref"`
-	Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"`
+	Ref        string         `json:"$ref" yaml:"$ref"`
+	Extensions map[string]any `json:"-" yaml:"-"`
+	Origin     *Origin        `json:"__origin__,omitempty" yaml:"__origin__,omitempty"`
 }
     Ref is specified by OpenAPI/Swagger 3.0 standard. See
     https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#reference-object
 
+func (x Ref) MarshalJSON() ([]byte, error)
+    MarshalJSON returns the JSON encoding of Ref.
+
+func (x Ref) MarshalYAML() (any, error)
+    MarshalYAML returns the YAML encoding of Ref.
+
+func (e *Ref) Validate(ctx context.Context, opts ...ValidationOption) error
+    Validate returns an error if Extensions does not comply with the OpenAPI
+    spec.
+
 type RefNameResolver func(*T, ComponentRef) string
     RefNameResolver maps a component to a name that is used as it's internalized
     name.

openapi3/internalize_refs.go

@@ -347,7 +347,7 @@ func (doc *T) derefSchema(s *Schema, refNameResolver RefNameResolver, parentIsEx
 
 	// Discriminator mapping values are special cases since they are not full
 	// ref objects but are string references to schema objects.
-	if s.Discriminator != nil && s.Discriminator.Mapping != nil {
+	if s.Discriminator != nil {
 		for k, mapRef := range s.Discriminator.Mapping {
 			s2 := (*SchemaRef)(&mapRef)
 			isExternal := doc.addSchemaToSpec(s2, refNameResolver, parentIsExternal)

openapi3/loader.go

@@ -975,7 +975,7 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat
 	// Only resolve refs that look like external references (contain a path).
 	// Plain schema names like "Dog" or internal refs like "#/components/schemas/Dog"
 	// don't need to be resolved by the loader.
-	if value.Discriminator != nil && value.Discriminator.Mapping != nil {
+	if value.Discriminator != nil {
 		for k, v := range value.Discriminator.Mapping {
 			// Only resolve if it looks like an external ref (contains path separator)
 			if strings.Contains(v.Ref, "/") && !strings.HasPrefix(v.Ref, "#") {

openapi3/ref.go

@@ -1,10 +1,43 @@
 package openapi3
 
+import (
+	"context"
+	"encoding/json"
+)
+
 //go:generate go run refsgenerator.go
 
 // Ref is specified by OpenAPI/Swagger 3.0 standard.
 // See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#reference-object
 type Ref struct {
-	Ref    string  `json:"$ref" yaml:"$ref"`
-	Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"`
+	Ref        string         `json:"$ref" yaml:"$ref"`
+	Extensions map[string]any `json:"-" yaml:"-"`
+	Origin     *Origin        `json:"__origin__,omitempty" yaml:"__origin__,omitempty"`
+}
+
+// MarshalYAML returns the YAML encoding of Ref.
+func (x Ref) MarshalYAML() (any, error) {
+	m := make(map[string]any, 1+len(x.Extensions))
+	for k, v := range x.Extensions {
+		m[k] = v
+	}
+	if x := x.Ref; x != "" {
+		m["$ref"] = x
+	}
+	return m, nil
+}
+
+// MarshalJSON returns the JSON encoding of Ref.
+func (x Ref) MarshalJSON() ([]byte, error) {
+	y, err := x.MarshalYAML()
+	if err != nil {
+		return nil, err
+	}
+	return json.Marshal(y)
+}
+
+// Validate returns an error if Extensions does not comply with the OpenAPI spec.
+func (e *Ref) Validate(ctx context.Context, opts ...ValidationOption) error {
+	ctx = WithValidationOptions(ctx, opts...)
+	return validateExtensions(ctx, e.Extensions)
 }

openapi3/refs.go

@@ -54,7 +54,7 @@ func (x *{{ $type.Name }}Ref) setRefPath(u *url.URL) {
 // MarshalYAML returns the YAML encoding of {{ $type.Name }}Ref.
 func (x {{ $type.Name }}Ref) MarshalYAML() (any, error) {
 	if ref := x.Ref; ref != "" {
-		return &Ref{Ref: ref}, nil
+		return &Ref{Ref: ref, Extensions: x.Extensions}, nil
 	}
 	return x.Value.MarshalYAML()
 }

openapi3/refs.tmpl

@@ -12,6 +12,7 @@ import (
 {{ range $type := .Types }}
 func Test{{ $type.Name }}Ref_Extensions(t *testing.T) {
 	data := []byte(`{"$ref":"#/components/schemas/Pet","something":"integer","x-order":1}`)
+	expectMarshalJson := []byte(`{"$ref":"#/components/schemas/Pet","x-order":1}`)
 
 	ref := {{ $type.Name }}Ref{}
 	err := json.Unmarshal(data, &ref)
@@ -34,6 +35,12 @@ func Test{{ $type.Name }}Ref_Extensions(t *testing.T) {
 	err = ref.Validate(context.Background(), AllowExtraSiblingFields("something"))
 	assert.ErrorContains(t, err, "found unresolved ref") // expected since value not defined
 
+	// Verify round trip JSON
+	// Compare as string to make error message more readable if different
+	outJson, err := ref.MarshalJSON()
+	assert.NoError(t, err)
+	assert.Equal(t, string(outJson), string(expectMarshalJson), "MarshalJSON output is not the same as input data")
+
 	// non-extension not json lookable
 	_, err = ref.JSONLookup("something")
 	assert.Error(t, err)

openapi3/refs_test.go

@@ -105,7 +105,7 @@ func ValidateRequest(ctx context.Context, input *RequestValidationInput) error {
 		if options.RejectWhenRequestBodyNotSpecified && input.Request.ContentLength > 0 {
 			err := &RequestError{
 				Input: input,
-				Err:   fmt.Errorf("request body not allowed for this request"),
+				Err:   errors.New("request body not allowed for this request"),
 			}
 			if !options.MultiError {
 				return err