Add openapi3.Schema.OrderedPropertyKeys

This commit adds the `OrderedPropertyKeys` method to the
`openapi3.Schema`:

    OrderedPropertyKeys returns the keys of the properties in the order
    they were defined. This is useful for generating code that needs to
    iterate over the properties in a consistent order. If the keys could
    not be extracted for some reason, then this method automatically
    sorts the keys to be deterministic.

This is done via a temporary fork of the YAML-to-JSON transformation library.
It will not be ready until invopop/yaml#13 is merged.

go.mod

@@ -2,6 +2,8 @@ module github.com/getkin/kin-openapi
 
 go 1.20
 
+replace github.com/invopop/yaml => github.com/diamondburned/invopop-yaml v0.3.2-0.20240812084936-33aae275be98
+
 require (
 	github.com/go-openapi/jsonpointer v0.21.0
 	github.com/gorilla/mux v1.8.0

go.sum

@@ -1,14 +1,14 @@
 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/diamondburned/invopop-yaml v0.3.2-0.20240812084936-33aae275be98 h1:Z+YbYkmppSq0GA/nr1d8+VVf3UpALBQSyFYixw7gb44=
+github.com/diamondburned/invopop-yaml v0.3.2-0.20240812084936-33aae275be98/go.mod h1:PMOp3nn4/12yEZUFfmOuNHJsZToEEOwoWsT+D81KkeA=
 github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ=
 github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY=
 github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE=
 github.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ=
 github.com/go-test/deep v1.0.8 h1:TDsG77qcSprGbC6vTN8OuXp5g+J+b5Pcguhf7Zt61VM=
 github.com/gorilla/mux v1.8.0 h1:i40aqfkR1h2SlN9hojwV5ZA91wcXFOvkdNIeFDP5koI=
 github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So=
-github.com/invopop/yaml v0.3.1 h1:f0+ZpmhfBSS4MhG+4HYseMdJhoeeopbSKbq5Rpeelso=
-github.com/invopop/yaml v0.3.1/go.mod h1:PMOp3nn4/12yEZUFfmOuNHJsZToEEOwoWsT+D81KkeA=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=

openapi3/marsh.go

@@ -1,8 +1,10 @@
 package openapi3
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
+	"log"
 	"strings"
 
 	"github.com/invopop/yaml"
@@ -32,3 +34,41 @@ func unmarshal(data []byte, v any) error {
 	// If both unmarshaling attempts fail, return a new error that includes both errors
 	return fmt.Errorf("failed to unmarshal data: json error: %v, yaml error: %v", jsonErr, yamlErr)
 }
+
+// extractObjectKeys extracts the keys of an object in a JSON string. The keys
+// are returned in the order they appear in the JSON string.
+func extractObjectKeys(b []byte) ([]string, error) {
+	if !bytes.HasPrefix(b, []byte{'{'}) {
+		return nil, fmt.Errorf("expected '{' at start of JSON object")
+	}
+
+	dec := json.NewDecoder(bytes.NewReader(b))
+	var keys []string
+
+	for dec.More() {
+		// Read prop name
+		t, err := dec.Token()
+		if err != nil {
+			log.Printf("Err: %v", err)
+			break
+		}
+
+		name, ok := t.(string)
+		if !ok {
+			continue // May be a delimeter
+		}
+
+		keys = append(keys, name)
+
+		var whatever nullMessage
+		dec.Decode(&whatever)
+	}
+
+	return keys, nil
+}
+
+// nullMessage implements json.Unmarshaler and does nothing with the given
+// value.
+type nullMessage struct{}
+
+func (*nullMessage) UnmarshalJSON(data []byte) error { return nil }

openapi3/marsh_test.go

@@ -76,3 +76,14 @@ paths:
 	err = doc.Validate(sl.Context)
 	require.NoError(t, err)
 }
+
+func TestExtractObjectKeys(t *testing.T) {
+	const j = `{
+		"z_hello": "world",
+		"a_foo": "bar",
+	}`
+
+	keys, err := extractObjectKeys([]byte(j))
+	require.NoError(t, err)
+	require.Equal(t, []string{"z_hello", "a_foo"}, keys)
+}

openapi3/schema.go

@@ -131,6 +131,8 @@ type Schema struct {
 	MaxProps             *uint64              `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
 	AdditionalProperties AdditionalProperties `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
 	Discriminator        *Discriminator       `json:"discriminator,omitempty" yaml:"discriminator,omitempty"`
+	// list of keys in Properties with preserved order
+	propertyKeys []string
 }
 
 type Types []string
@@ -410,6 +412,16 @@ func (schema *Schema) UnmarshalJSON(data []byte) error {
 	if err := json.Unmarshal(data, &x); err != nil {
 		return unmarshalError(err)
 	}
+
+	if x.Properties != nil {
+		var rawProperties struct {
+			Properties json.RawMessage `json:"properties"`
+		}
+		if err := json.Unmarshal(data, &rawProperties); err == nil {
+			x.propertyKeys, _ = extractObjectKeys(rawProperties.Properties)
+		}
+	}
+
 	_ = json.Unmarshal(data, &x.Extensions)
 
 	delete(x.Extensions, "oneOf")
@@ -476,6 +488,24 @@ func (schema *Schema) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// OrderedPropertyKeys returns the keys of the properties in the order they were
+// defined. This is useful for generating code that needs to iterate over the
+// properties in a consistent order. If the keys could not be extracted for some
+// reason, then this method automatically sorts the keys to be deterministic.
+func (schema Schema) OrderedPropertyKeys() []string {
+	if schema.propertyKeys != nil {
+		return schema.propertyKeys
+	}
+
+	keys := make([]string, 0, len(schema.Properties))
+	for k := range schema.Properties {
+		keys = append(keys, k)
+	}
+
+	sort.Strings(keys)
+	return keys
+}
+
 // JSONLookup implements https://pkg.go.dev/github.com/go-openapi/jsonpointer#JSONPointable
 func (schema Schema) JSONLookup(token string) (any, error) {
 	switch token {

openapi3/schema_test.go

@@ -1490,3 +1490,30 @@ func TestIssue751(t *testing.T) {
 	require.NoError(t, schema.VisitJSON(validData))
 	require.ErrorContains(t, schema.VisitJSON(invalidData), "duplicate items found")
 }
+
+func TestSchemaOrderedProperties(t *testing.T) {
+	const api = `
+openapi: "3.0.1"
+components:
+  schemas:
+    Pet:
+      properties:
+        z_name:
+          type: string
+          description: Diamond
+        a_ownerName:
+          not:
+            type: boolean
+      type: object
+`
+	s, err := NewLoader().LoadFromData([]byte(api))
+	require.NoError(t, err)
+	require.NotNil(t, s)
+
+	pet := s.Components.Schemas["Pet"].Value
+	require.Equal(t, []string{"z_name", "a_ownerName"}, pet.propertyKeys)
+	require.Equal(t, []string{"z_name", "a_ownerName"}, pet.OrderedPropertyKeys())
+
+	pet.propertyKeys = nil
+	require.Equal(t, []string{"a_ownerName", "z_name"}, pet.OrderedPropertyKeys())
+}