Add function to check if a schema matches the root document's

It does this by keeping track of the source file paths of schemas in
multi-file'd specs.

This enables the amalgamation of schemas which reference the same underlying
model which removes *very annoying* to use anonymous structs in generated
models when using codegen tools like oapi-codegen.

Author: percivalalb

openapi3/loader.go

@@ -186,6 +186,11 @@ func (loader *Loader) ResolveRefsIn(doc *T, location *url.URL) (err error) {
 		loader.resetVisitedPathItemRefs()
 	}
 
+	if location != nil {
+		specURL := *location
+		doc.url = &specURL // shallow-copy
+	}
+
 	if components := doc.Components; components != nil {
 		for _, component := range components.Headers {
 			if err = loader.resolveHeaderRef(doc, component, location); err != nil {
@@ -787,6 +792,12 @@ func (loader *Loader) resolveSchemaRef(doc *T, component *SchemaRef, documentPat
 	}
 
 	if ref := component.Ref; ref != "" {
+		if documentPath != nil {
+			refURL := *documentPath // shallow-clone
+			refURL.Path = path.Join(path.Dir(documentPath.Path), ref)
+			component.refURL = &refURL
+		}
+
 		if isSingleRefElement(ref) {
 			var schema Schema
 			if documentPath, err = loader.loadSingleElementFromURI(ref, documentPath, &schema); err != nil {

openapi3/openapi3.go

@@ -5,6 +5,9 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net/url"
+	"path"
+	"strings"
 
 	"github.com/go-openapi/jsonpointer"
 )
@@ -24,6 +27,96 @@ type T struct {
 	ExternalDocs *ExternalDocs        `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
 
 	visited visitedComponent
+	url     *url.URL
+}
+
+// MatchesSchemaInRootDocument returns if the given schema is identical
+// to a schema defined in the root document's '#/components/schemas'.
+// It returns a reference to the schema in the form
+// '#/components/schemas/NameXXX'
+//
+// Of course given it a schema from the root document will always match.
+//
+// https://swagger.io/docs/specification/using-ref/#syntax
+//
+// Case 1: Directly via
+//
+//	../openapi.yaml#/components/schemas/Record
+//
+// Case 2: Or indirectly by using a $ref which matches a schema
+// in the root document's '#/components/schemas' using the same
+// $ref.
+//
+// In schemas/record.yaml
+//
+//	$ref: ./record.yaml
+//
+// In openapi.yaml
+//
+//	  components:
+//	    schemas:
+//		  Record:
+//		    $ref: schemas/record.yaml
+func (doc *T) MatchesSchemaInRootDocument(sch *SchemaRef) (string, bool) {
+	// Case 1:
+	// Something like: ../another-folder/document.json#/myElement
+	if isRemoteReference(sch.Ref) && isSchemaReference(sch.Ref) {
+		// Determine if it is *this* root doc.
+		if sch.referencesRootDocument(doc) {
+			_, name, _ := strings.Cut(sch.Ref, "#/components/schemas")
+
+			return path.Join("#/components/schemas", name), true
+		}
+	}
+
+	// If there are no schemas defined in the root document return early.
+	if doc.Components == nil || doc.Components.Schemas == nil {
+		return "", false
+	}
+
+	// Case 2:
+	// Something like: ../openapi.yaml#/components/schemas/myElement
+	for name, s := range doc.Components.Schemas {
+		// Must be a reference to a YAML file.
+		if !isWholeDocumentReference(s.Ref) {
+			continue
+		}
+
+		// Is the schema a ref to the same resource.
+		if !sch.refersToSameDocument(s) {
+			continue
+		}
+
+		// Transform the remote ref to the equivalent schema in the root document.
+		return path.Join("#/components/schemas", name), true
+	}
+
+	return "", false
+}
+
+// isElementReference takes a $ref value and checks if it references a specific element.
+func isElementReference(ref string) bool {
+	return ref != "" && !isWholeDocumentReference(ref)
+}
+
+// isSchemaReference takes a $ref value and checks if it references a schema element.
+func isSchemaReference(ref string) bool {
+	return isElementReference(ref) && strings.Contains(ref, "#/components/schemas")
+}
+
+// isWholeDocumentReference takes a $ref value and checks if it is whole document reference.
+func isWholeDocumentReference(ref string) bool {
+	return ref != "" && !strings.ContainsAny(ref, "#")
+}
+
+// isRemoteReference takes a $ref value and checks if it is remote reference.
+func isRemoteReference(ref string) bool {
+	return ref != "" && !strings.HasPrefix(ref, "#") && !isURLReference(ref)
+}
+
+// isURLReference takes a $ref value and checks if it is URL reference.
+func isURLReference(ref string) bool {
+	return strings.HasPrefix(ref, "http://") || strings.HasPrefix(ref, "https://") || strings.HasPrefix(ref, "//")
 }
 
 var _ jsonpointer.JSONPointable = (*T)(nil)

openapi3/refs.go

@@ -4,7 +4,9 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/url"
 	"sort"
+	"strings"
 
 	"github.com/go-openapi/jsonpointer"
 	"github.com/perimeterx/marshmallow"
@@ -562,10 +564,50 @@ type SchemaRef struct {
 	Ref   string
 	Value *Schema
 	extra []string
+
+	// Only non-nil if Ref is non-empty, might be nil even if Ref is non-empty
+	// if loaded from a in-memory schema that has been merged.
+	refURL *url.URL
 }
 
 var _ jsonpointer.JSONPointable = (*SchemaRef)(nil)
 
+// refersToSameDocument returns if the $ref refers to the same document.
+//
+// Documents in different directories will have distinct $ref values that resolve to
+// the same document.
+// For example, consider the 3 files:
+//
+//	/records.yaml
+//	/root.yaml         $ref: records.yaml
+//	/schema/other.yaml $ref: ../records.yaml
+//
+// The records.yaml reference in the 2 latter refers to the same document.
+func (x *SchemaRef) refersToSameDocument(o *SchemaRef) bool {
+	if x == nil || x.refURL == nil || o == nil || o.refURL == nil {
+		return false
+	}
+
+	// refURL is relative to the working directory & base spec file.
+	return x.refURL.String() == o.refURL.String()
+}
+
+// referencesRootDocument returns if the given schema matches the root document of the OpenAPI spec.
+//
+// If the document has no location, perhaps loaded from data in memory, it always returns false.
+func (x *SchemaRef) referencesRootDocument(doc *T) bool {
+	if doc.url == nil || x == nil || x.refURL == nil {
+		return false
+	}
+
+	refURL := *x.refURL
+
+	refURL.Path, _, _ = strings.Cut(refURL.Path, "#") // remove the document element reference
+
+	// Check referenced element was in the root document.
+	return doc.url.String() == refURL.String()
+}
+
 func (x *SchemaRef) isEmpty() bool { return x == nil || x.Ref == "" && x.Value == nil }
 
 // MarshalYAML returns the YAML encoding of SchemaRef.