doc: added basic usage in readme and testable examples

Signed-off-by: Frédéric BIDON <fredbi@yahoo.com>

Author: fredbi

README.md

@@ -30,6 +30,21 @@ go get github.com/go-openapi/jsonreference
 
 ## Basic usage
 
+```go
+// Creating a new reference
+ref, err := jsonreference.New("http://example.com/doc.json#/definitions/Pet")
+
+// Fragment-only reference
+fragRef := jsonreference.MustCreateRef("#/definitions/Pet")
+
+// Resolving references
+parent, _ := jsonreference.New("http://example.com/base.json")
+child, _ := jsonreference.New("#/definitions/Pet")
+resolved, _ := parent.Inherits(child)
+// Result: "http://example.com/base.json#/definitions/Pet"
+```
+
+
 ## Change log
 
 See <https://github.com/go-openapi/jsonreference/releases>

SECURITY.md

@@ -6,7 +6,7 @@ This policy outlines the commitment and practices of the go-openapi maintainers
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 0.22.x  | :white_check_mark: |
+| 0.21.x  | :white_check_mark: |
 
 ## Reporting a vulnerability
 

examples_test.go

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: Copyright (c) 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package jsonreference_test
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/go-openapi/jsonreference"
+)
+
+func ExampleRef_GetURL() {
+	fragRef := jsonreference.MustCreateRef("#/definitions/Pet")
+
+	fmt.Printf("URL: %s\n", fragRef.GetURL())
+
+	// Output: URL: #/definitions/Pet
+}
+
+func ExampleRef_Inherits() {
+	parent := jsonreference.MustCreateRef("http://example.com/base.json")
+	child, err := jsonreference.New("#/definitions/Pet")
+	if err != nil {
+		log.Printf("%v", err)
+
+		return
+	}
+
+	resolved, err := parent.Inherits(child)
+	if err != nil {
+		log.Printf("%v", err)
+
+		return
+	}
+
+	fmt.Printf("URL: %v\n", resolved)
+
+	// Output: URL: http://example.com/base.json#/definitions/Pet
+}

reference.go

@@ -16,6 +16,7 @@ const (
 	fragmentRune = `#`
 )
 
+// ErrChildURL is raised when there is no child.
 var ErrChildURL = errors.New("child url is nil")
 
 // Ref represents a json reference object.