Add support for refs

Author: marcusolsson

go.mod

@@ -2,4 +2,9 @@ module github.com/grafana/json-schema-docs
 
 go 1.14
 
-require github.com/olekukonko/tablewriter v0.0.4
+require (
+	github.com/bitly/go-simplejson v0.5.0
+	github.com/davecgh/go-spew v1.1.1
+	github.com/olekukonko/tablewriter v0.0.4
+	github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb
+)

go.sum

@@ -1,4 +1,10 @@
+github.com/bitly/go-simplejson v0.5.0 h1:6IH+V8/tVMab511d5bn4M7EwGXZf9Hj6i2xSwkNEM+Y=
+github.com/bitly/go-simplejson v0.5.0/go.mod h1:cXHtHw4XUPsvGaxgjIAn8PhEWG9NfngEKAMDJEczWVA=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/mattn/go-runewidth v0.0.7 h1:Ei8KR0497xHyKJPAv59M1dkC+rOZCMBJ+t3fZ+twI54=
 github.com/mattn/go-runewidth v0.0.7/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
 github.com/olekukonko/tablewriter v0.0.4 h1:vHD/YYe1Wolo78koG299f7V/VAS08c6IpCLn+Ejf/w8=
 github.com/olekukonko/tablewriter v0.0.4/go.mod h1:zq6QwlOf5SlnkVbMSr5EoBv3636FWnp+qbPhuoO21uA=
+github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb h1:zGWFAtiMcyryUHoUjUJX0/lt1H2+i2Ka2n+D3DImSNo=
+github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=

main.go

@@ -1,8 +1,10 @@
 package main
 
 import (
+	"encoding/json"
 	"flag"
 	"fmt"
+	"io/ioutil"
 	"log"
 	"os"
 	"text/template"
@@ -27,11 +29,14 @@ func main() {
 	}
 	defer f.Close()
 
-	schema, err := newSchema(f)
+	schema, err := newSchema(f, ".")
 	if err != nil {
 		log.Fatal(err)
 	}
 
+	b, _ := json.MarshalIndent(schema, "", "  ")
+	ioutil.WriteFile("new.json", b, 0644)
+
 	tpl, err := getOrDefaultTemplate(*templatePath)
 	if err != nil {
 		log.Fatal(err)

ref.go

@@ -0,0 +1,136 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/bitly/go-simplejson"
+	"github.com/xeipuuv/gojsonpointer"
+)
+
+func dumpSchema(schem *schema) {
+	b, _ := json.MarshalIndent(schem, "", "  ")
+	fmt.Println(string(b))
+}
+
+// resolveSchema recursively resolves schemas.
+func resolveSchema(schem *schema, dir string, root *simplejson.Json) (*schema, error) {
+	for _, prop := range schem.Properties {
+		if prop.Ref != "" {
+			tmp, err := resolveReference(prop.Ref, dir, root)
+			if err != nil {
+				return nil, err
+			}
+			*prop = *tmp
+		}
+		foo, err := resolveSchema(prop, dir, root)
+		if err != nil {
+			return nil, err
+		}
+		*prop = *foo
+	}
+
+	if schem.Items != nil {
+		if schem.Items.Ref != "" {
+			tmp, err := resolveReference(schem.Items.Ref, dir, root)
+			if err != nil {
+				return nil, err
+			}
+			*schem.Items = *tmp
+		}
+		foo, err := resolveSchema(schem.Items, dir, root)
+		if err != nil {
+			return nil, err
+		}
+		*schem.Items = *foo
+	}
+
+	return schem, nil
+}
+
+// resolveReference loads a schema from a $ref.
+//
+// If ref contains a hashtag (#), the part before represents a cross-schema
+// reference, and the part after represents a in-schema reference.
+//
+// If ref is missing a hashtag, the whole schema is being referenced.
+func resolveReference(ref string, dir string, root *simplejson.Json) (*schema, error) {
+	i := strings.Index(ref, "#")
+
+	if i < 0 {
+		// cross-schema reference to another schema
+		schema, err := loadSchemaFromPath(filepath.Join(dir, ref))
+		if err != nil {
+			return nil, err
+		}
+		return schema, nil
+	} else if i == 0 {
+		// in-schema reference
+		return resolveInSchemaReference(ref[i+1:], root)
+	} else {
+
+		schema, err := loadSchemaFromPath(filepath.Join(dir, ref[:i]))
+		if err != nil {
+			return nil, err
+		}
+
+		b, _ := json.Marshal(schema)
+		newRoot, _ := simplejson.NewJson(b)
+		return resolveInSchemaReference(ref[i+1:], newRoot)
+	}
+
+}
+
+func resolveInSchemaReference(path string, root *simplejson.Json) (*schema, error) {
+	// in-schema reference
+	pointer, err := gojsonpointer.NewJsonPointer(path)
+	if err != nil {
+		return nil, err
+	}
+
+	v, _, err := pointer.Get(root.MustMap())
+	if err != nil {
+		return nil, err
+	}
+
+	var sch schema
+	b, err := json.Marshal(v)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := json.Unmarshal(b, &sch); err != nil {
+		return nil, err
+	}
+
+	return &sch, nil
+}
+
+// loadSchemaFromPath returns a schema at a given path.
+func loadSchemaFromPath(path string) (*schema, error) {
+	rc, err := openFileOrURL(path)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer rc.Close()
+
+	return newSchema(rc, filepath.Dir(path))
+}
+
+// openFileOrURL opens a file from a URL or local path.
+func openFileOrURL(path string) (io.ReadCloser, error) {
+	if strings.HasPrefix(path, "http://") || strings.HasPrefix(path, "https://") {
+		resp, err := http.Get(path)
+		if err != nil {
+			return nil, err
+		}
+		return resp.Body, nil
+	}
+	return os.Open(path)
+}

schema.go

@@ -3,27 +3,33 @@ package main
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"io/ioutil"
 	"sort"
 	"strings"
 
+	"github.com/bitly/go-simplejson"
 	"github.com/olekukonko/tablewriter"
 )
 
+var errCrossSchemaReference = errors.New("cross-schema reference")
+
 type schema struct {
-	ID          string            `json:"$id"`
-	Schema      string            `json:"$schema"`
-	Title       string            `json:"title"`
-	Description string            `json:"description"`
-	Required    []string          `json:"required"`
-	Type        string            `json:"type"`
-	Properties  map[string]schema `json:"properties"`
-	Items       *schema           `json:"items"`
+	ID          string             `json:"$id,omitempty"`
+	Ref         string             `json:"$ref,omitempty"`
+	Schema      string             `json:"$schema,omitempty"`
+	Title       string             `json:"title,omitempty"`
+	Description string             `json:"description,omitempty"`
+	Required    []string           `json:"required,omitempty"`
+	Type        string             `json:"type,omitempty"`
+	Properties  map[string]*schema `json:"properties,omitempty"`
+	Items       *schema            `json:"items,omitempty"`
+	Definitions map[string]*schema `json:"definitions,omitempty"`
 }
 
-func newSchema(r io.Reader) (*schema, error) {
+func newSchema(r io.Reader, workingDir string) (*schema, error) {
 	b, err := ioutil.ReadAll(r)
 	if err != nil {
 		return nil, err
@@ -34,7 +40,13 @@ func newSchema(r io.Reader) (*schema, error) {
 		return nil, err
 	}
 
-	return &data, nil
+	// Needed for resolving in-schema references.
+	root, err := simplejson.NewJson(b)
+	if err != nil {
+		return nil, err
+	}
+
+	return resolveSchema(&data, workingDir, root)
 }
 
 // Markdown returns the Markdown representation of the schema.
@@ -63,20 +75,22 @@ func (s schema) Markdown(level int) string {
 		fmt.Fprintln(&buf)
 	}
 
-	table := tablewriter.NewWriter(&buf)
-	table.SetHeader([]string{"Property", "Type", "Required", "Description"})
-	table.SetBorders(tablewriter.Border{Left: true, Top: false, Right: true, Bottom: false})
-	table.SetCenterSeparator("|")
-	table.SetAutoFormatHeaders(false)
-	table.SetHeaderAlignment(tablewriter.ALIGN_LEFT)
-	table.SetAutoWrapText(false)
+	printProperties(&buf, &s)
+
+	// Add padding.
+	fmt.Fprintln(&buf)
 
+	for _, obj := range findDefinitions(&s) {
+		fmt.Fprintf(&buf, obj.Markdown(level+1))
+	}
+
+	return buf.String()
+}
+
+func findDefinitions(s *schema) []*schema {
 	// Gather all properties of object type so that we can generate the
 	// properties for them recursively.
-	var objs []schema
-
-	// Buffer all property rows so that we can sort them before printing them.
-	var rows [][]string
+	var objs []*schema
 
 	for k, p := range s.Properties {
 		// Use the identifier as the title.
@@ -87,21 +101,49 @@ func (s schema) Markdown(level int) string {
 
 		// If the property is an array of objects, use the name of the array
 		// property as the title.
-		if p.Type == "array" && p.Items != nil {
-			if p.Items.Type == "object" {
-				p.Items.Title = k
-				objs = append(objs, *p.Items)
+		if p.Type == "array" {
+			if p.Items != nil {
+				if p.Items.Type == "object" {
+					p.Items.Title = k
+					objs = append(objs, p.Items)
+				}
 			}
 		}
+	}
 
+	// Sort the object schemas.
+	sort.Slice(objs, func(i, j int) bool {
+		return objs[i].Title < objs[j].Title
+	})
+
+	return objs
+}
+
+func printProperties(w io.Writer, s *schema) {
+	table := tablewriter.NewWriter(w)
+	table.SetHeader([]string{"Property", "Type", "Required", "Description"})
+	table.SetBorders(tablewriter.Border{Left: true, Top: false, Right: true, Bottom: false})
+	table.SetCenterSeparator("|")
+	table.SetAutoFormatHeaders(false)
+	table.SetHeaderAlignment(tablewriter.ALIGN_LEFT)
+	table.SetAutoWrapText(false)
+
+	// Buffer all property rows so that we can sort them before printing them.
+	var rows [][]string
+
+	for k, p := range s.Properties {
 		// Generate relative links for objects and arrays of objects.
 		var propType string
 		switch p.Type {
 		case "object":
 			propType = fmt.Sprintf("[%s](#%s)", p.Type, strings.ToLower(k))
 		case "array":
 			if p.Items != nil {
-				propType = fmt.Sprintf("[%s](#%s)", p.Type, strings.ToLower(k))
+				if p.Items.Type == "object" {
+					propType = fmt.Sprintf("[%s](#%s)[]", p.Items.Type, strings.ToLower(k))
+				} else {
+					propType = fmt.Sprintf("%s[]", p.Items.Type)
+				}
 			} else {
 				propType = p.Type
 			}
@@ -133,19 +175,6 @@ func (s schema) Markdown(level int) string {
 
 	table.AppendBulk(rows)
 	table.Render()
-
-	// Add padding.
-	fmt.Fprintln(&buf)
-
-	// Sort the object schemas before recursing.
-	sort.Slice(objs, func(i, j int) bool {
-		return objs[i].Title < objs[j].Title
-	})
-	for _, obj := range objs {
-		fmt.Fprintf(&buf, obj.Markdown(level+1))
-	}
-
-	return buf.String()
 }
 
 // in returns true if a string slice contains a specific string.

schema_test.go

@@ -23,6 +23,7 @@ func TestSchema(t *testing.T) {
 		{name: "calendar", schema: "calendar.schema.json"},
 		{name: "card", schema: "card.schema.json"},
 		{name: "geographical-location", schema: "geographical-location.schema.json"},
+		{name: "ref-hell", schema: "ref-hell.schema.json"},
 	}
 
 	for _, tt := range schemaTests {
@@ -33,7 +34,7 @@ func TestSchema(t *testing.T) {
 			}
 			defer f.Close()
 
-			schema, err := newSchema(f)
+			schema, err := newSchema(f, "testdata")
 			if err != nil {
 				t.Fatal(err)
 			}
@@ -54,6 +55,7 @@ func TestSchema(t *testing.T) {
 			}
 
 			if !bytes.Equal(buf.Bytes(), g) {
+				t.Log(buf.String())
 				t.Errorf("data does not match .golden file")
 			}
 		})

testdata/TestSchema_arrays.golden

@@ -2,8 +2,17 @@ A representation of a person, company, organization, or place
 
 ## Properties
 
-| Property     | Type                 | Required | Description |
-|--------------|----------------------|----------|-------------|
-| `fruits`     | [array](#fruits)     | No       |             |
-| `vegetables` | [array](#vegetables) | No       |             |
+| Property     | Type                    | Required | Description |
+|--------------|-------------------------|----------|-------------|
+| `fruits`     | string[]                | No       |             |
+| `vegetables` | [object](#vegetables)[] | No       |             |
+
+## vegetables
+
+### Properties
+
+| Property     | Type    | Required | Description                |
+|--------------|---------|----------|----------------------------|
+| `veggieLike` | boolean | **Yes**  | Do I like this vegetable?  |
+| `veggieName` | string  | **Yes**  | The name of the vegetable. |