(Documentation) Use OpenAPI-compatible type names in docs (#1469)

CHANGELOG.md

@@ -13,6 +13,7 @@
 - (Feature) Member Memory Reservation
 - (Documentation) Update ArangoDeploymentReplication and ArangoLocalStorage CR auto-generated docs
 - (Feature) Add ArangoMember Message and extend ArangoMember CRD
+- (Documentation) Use OpenAPI-compatible type names in docs
 
 ## [1.2.34](https://github.com/arangodb/kube-arangodb/tree/1.2.34) (2023-10-16)
 - (Bugfix) Fix make manifests-crd-file command

docs/api/ArangoBackup.V1.md

@@ -2,25 +2,25 @@
 
 ## Spec
 
-### .spec.backoff.iterations: int
+### .spec.backoff.iterations: integer
 
 Iterations defines number of iterations before reaching MaxDelay. Default to 5
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec_backoff.go#L31)
 
-### .spec.backoff.max_delay: int
+### .spec.backoff.max_delay: integer
 
 MaxDelay defines maximum delay in seconds. Default to 600
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec_backoff.go#L29)
 
-### .spec.backoff.max_iterations: int
+### .spec.backoff.max_iterations: integer
 
 MaxIterations defines maximum number of iterations after backoff will be disabled. Default to nil (no limit)
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec_backoff.go#L33)
 
-### .spec.backoff.min_delay: int
+### .spec.backoff.min_delay: integer
 
 MinDelay defines minimum delay in seconds. Default to 30
 
@@ -72,13 +72,13 @@ This field is **immutable**: can't be changed after backup creation
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec.go#L77)
 
-### .spec.lifetime: int64
+### .spec.lifetime: integer
 
 Lifetime is the time after which the backup will be deleted. Format: "1.5h" or "2h45m".
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec.go#L47)
 
-### .spec.options.allowInconsistent: bool
+### .spec.options.allowInconsistent: boolean
 
 AllowInconsistent flag for Backup creation request.
 If this value is set to true, backup is taken even if we are not able to acquire lock.
@@ -89,7 +89,7 @@ This field is **immutable**: can't be changed after backup creation
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec.go#L66)
 
-### .spec.options.timeout: float32
+### .spec.options.timeout: number
 
 Timeout for Backup creation request in seconds.
 
@@ -139,17 +139,17 @@ This field is **immutable**: can't be changed after backup creation
 
 ## Status
 
-### .status.available: bool
+### .status.available: boolean
 
 Available Determines if we can restore from ArangoBackup
 
 [Code Reference](/pkg/apis/backup/v1/backup_status.go#L36)
 
-### .status.backoff.iterations: int
+### .status.backoff.iterations: integer
 
 [Code Reference](/pkg/apis/backup/v1/backup_status_backoff.go#L30)
 
-### .status.backup.downloaded: bool
+### .status.backup.downloaded: boolean
 
 Downloaded Determines if ArangoBackup has been downloaded.
 
@@ -159,31 +159,31 @@ Downloaded Determines if ArangoBackup has been downloaded.
 
 [Code Reference](/pkg/apis/backup/v1/backup_status.go#L56)
 
-### .status.backup.imported: bool
+### .status.backup.imported: boolean
 
 [Code Reference](/pkg/apis/backup/v1/backup_status.go#L67)
 
-### .status.backup.keys: []string
+### .status.backup.keys: array
 
 [Code Reference](/pkg/apis/backup/v1/backup_status.go#L70)
 
-### .status.backup.numberOfDBServers: uint
+### .status.backup.numberOfDBServers: integer
 
 NumberOfDBServers Cluster size of the Backup in ArangoDB
 
 [Code Reference](/pkg/apis/backup/v1/backup_status.go#L62)
 
-### .status.backup.potentiallyInconsistent: bool
+### .status.backup.potentiallyInconsistent: boolean
 
 [Code Reference](/pkg/apis/backup/v1/backup_status.go#L58)
 
-### .status.backup.sizeInBytes: uint64
+### .status.backup.sizeInBytes: integer
 
 SizeInBytes Size of the Backup in ArangoDB.
 
 [Code Reference](/pkg/apis/backup/v1/backup_status.go#L60)
 
-### .status.backup.uploaded: bool
+### .status.backup.uploaded: boolean
 
 Uploaded Determines if ArangoBackup has been uploaded
 

docs/api/ArangoBackupPolicy.V1.md

@@ -2,7 +2,7 @@
 
 ## Spec
 
-### .spec.allowConcurrent: bool
+### .spec.allowConcurrent: boolean
 
 AllowConcurrent if false, ArangoBackup will not be created when previous Backups are not finished
 
@@ -10,7 +10,7 @@ Default Value: true
 
 [Code Reference](/pkg/apis/backup/v1/backup_policy_spec.go#L35)
 
-### .spec.maxBackups: int
+### .spec.maxBackups: integer
 
 MaxBackups defines how many backups should be kept in history (per deployment). Oldest healthy Backups will be deleted.
 If not specified or 0 then no limit is applied
@@ -35,37 +35,37 @@ Links:
 
 [Code Reference](/pkg/apis/backup/v1/backup_policy_spec.go#L39)
 
-### .spec.template.backoff.iterations: int
+### .spec.template.backoff.iterations: integer
 
 Iterations defines number of iterations before reaching MaxDelay. Default to 5
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec_backoff.go#L31)
 
-### .spec.template.backoff.max_delay: int
+### .spec.template.backoff.max_delay: integer
 
 MaxDelay defines maximum delay in seconds. Default to 600
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec_backoff.go#L29)
 
-### .spec.template.backoff.max_iterations: int
+### .spec.template.backoff.max_iterations: integer
 
 MaxIterations defines maximum number of iterations after backoff will be disabled. Default to nil (no limit)
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec_backoff.go#L33)
 
-### .spec.template.backoff.min_delay: int
+### .spec.template.backoff.min_delay: integer
 
 MinDelay defines minimum delay in seconds. Default to 30
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec_backoff.go#L27)
 
-### .spec.template.lifetime: int64
+### .spec.template.lifetime: integer
 
 Lifetime is the time after which the backup will be deleted. Format: "1.5h" or "2h45m".
 
 [Code Reference](/pkg/apis/backup/v1/backup_policy_spec.go#L61)
 
-### .spec.template.options.allowInconsistent: bool
+### .spec.template.options.allowInconsistent: boolean
 
 AllowInconsistent flag for Backup creation request.
 If this value is set to true, backup is taken even if we are not able to acquire lock.
@@ -76,7 +76,7 @@ This field is **immutable**: can't be changed after backup creation
 
 [Code Reference](/pkg/apis/backup/v1/backup_spec.go#L66)
 
-### .spec.template.options.timeout: float32
+### .spec.template.options.timeout: number
 
 Timeout for Backup creation request in seconds.
 

docs/api/ArangoDeploymentReplication.V1.md

@@ -2,14 +2,14 @@
 
 ## Spec
 
-### .spec.cancellation.ensureInSync: bool
+### .spec.cancellation.ensureInSync: boolean
 
 EnsureInSync if it is true then during cancellation process data consistency is required.
 Default value is true.
 
 [Code Reference](/pkg/apis/replication/v1/replication_spec.go#L38)
 
-### .spec.cancellation.sourceReadOnly: bool
+### .spec.cancellation.sourceReadOnly: boolean
 
 SourceReadOnly if it true then after cancellation source data center should be in read-only mode.
 Default value is false.
@@ -42,7 +42,7 @@ If set, this provides default values for masterEndpoint, auth & tls.
 
 [Code Reference](/pkg/apis/replication/v1/endpoint_spec.go#L36)
 
-### .spec.destination.masterEndpoint: []string
+### .spec.destination.masterEndpoint: array
 
 MasterEndpoint holds a list of URLs used to reach the syncmaster(s)
 Use this setting if the source cluster is not running inside a Kubernetes cluster
@@ -86,7 +86,7 @@ If set, this provides default values for masterEndpoint, auth & tls.
 
 [Code Reference](/pkg/apis/replication/v1/endpoint_spec.go#L36)
 
-### .spec.source.masterEndpoint: []string
+### .spec.source.masterEndpoint: array
 
 MasterEndpoint holds a list of URLs used to reach the syncmaster(s)
 Use this setting if the source cluster is not running inside a Kubernetes cluster

docs/api/ArangoLocalStorage.V1Alpha.md

@@ -2,31 +2,31 @@
 
 ## Spec
 
-### .spec.localPath: []string
+### .spec.localPath: array
 
 LocalPath setting specifies one or more local directories (on the nodes) used to create persistent volumes in.
 
 [Code Reference](/pkg/apis/storage/v1alpha/local_storage_spec.go#L36)
 
-### .spec.nodeSelector: map[string]string
+### .spec.nodeSelector: object
 
 NodeSelector setting specifies which nodes the operator will provision persistent volumes on.
 
 [Code Reference](/pkg/apis/storage/v1alpha/local_storage_spec.go#L43)
 
-### .spec.podCustomization.priority: int32
+### .spec.podCustomization.priority: integer
 
 Priority if defined, sets the priority for pods of storage provisioner
 
 [Code Reference](/pkg/apis/storage/v1alpha/local_storage_pod_customization.go#L25)
 
-### .spec.privileged: bool
+### .spec.privileged: boolean
 
 Privileged if set, passes Privileged flag to SecurityContext for pods of storage provisioner
 
 [Code Reference](/pkg/apis/storage/v1alpha/local_storage_spec.go#L45)
 
-### .spec.storageClass.isDefault: bool
+### .spec.storageClass.isDefault: boolean
 
 IsDefault setting specifies if the created `StorageClass` will
 be marked as default storage class.

docs/api/ArangoMember.V1.md

@@ -2,7 +2,7 @@
 
 ## Spec
 
-### .spec.deletion_priority: int
+### .spec.deletion_priority: integer
 
 DeletionPriority define Deletion Priority.
 Higher value means higher priority. Default is 0.
@@ -16,7 +16,7 @@ DeploymentUID define Deployment UID.
 
 [Code Reference](/pkg/apis/deployment/v1/arango_member_spec.go#L36)
 
-### .spec.group: int
+### .spec.group: integer
 
 Group define Member Groups.
 

internal/doc_definition_test.go

@@ -20,6 +20,11 @@
 
 package internal
 
+import (
+	"sort"
+	"strings"
+)
+
 type DocDefinitions []DocDefinition
 
 type DocDefinition struct {
@@ -42,3 +47,13 @@ type DocDefinition struct {
 	Default *string
 	Example []string
 }
+
+func (d DocDefinitions) Sort() {
+	sort.Slice(d, func(i, j int) bool {
+		a, b := strings.ToLower(d[i].Path), strings.ToLower(d[j].Path)
+		if a == b {
+			return d[i].Path < d[j].Path
+		}
+		return a < b
+	})
+}

internal/docs_parser_test.go

@@ -29,7 +29,6 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
-	"sort"
 	"strings"
 	"testing"
 
@@ -38,32 +37,17 @@ import (
 	"github.com/arangodb/kube-arangodb/pkg/util"
 )
 
-func parseDocDefinitions(t *testing.T, res map[string]*ast.Field, fs *token.FileSet) DocDefinitions {
+func parseDocDefinitions(t *testing.T, res map[typeInfo]*ast.Field, fs *token.FileSet) DocDefinitions {
 	root := os.Getenv("ROOT")
 	require.NotEmpty(t, root)
 
-	var elements []string
-	for k := range res {
-		elements = append(elements, k)
-	}
+	defs := make(DocDefinitions, 0, len(res))
 
-	sort.Slice(elements, func(i, j int) bool {
-		if a, b := strings.ToLower(elements[i]), strings.ToLower(elements[j]); a == b {
-			return elements[i] < elements[j]
-		} else {
-			return a < b
+	for info, field := range res {
+		def := DocDefinition{
+			Path: info.path,
+			Type: info.typ,
 		}
-	})
-
-	defs := make(DocDefinitions, len(elements))
-
-	for id, k := range elements {
-		field := res[k]
-
-		var def DocDefinition
-
-		def.Path = strings.Split(k, ":")[0]
-		def.Type = strings.Split(k, ":")[1]
 
 		require.NotNil(t, field)
 
@@ -105,13 +89,18 @@ func parseDocDefinitions(t *testing.T, res map[string]*ast.Field, fs *token.File
 		def.File = filePath
 		def.Line = file.Line(field.Pos())
 
-		defs[id] = def
+		defs = append(defs, def)
 	}
 	return defs
 }
 
-func iterateOverObject(t *testing.T, fields map[string]*ast.Field, name string, object reflect.Type, path string) map[string]*ast.Field {
-	r := map[string]*ast.Field{}
+type typeInfo struct {
+	path string
+	typ  string
+}
+
+func iterateOverObject(t *testing.T, fields map[string]*ast.Field, name string, object reflect.Type, path string) map[typeInfo]*ast.Field {
+	r := map[typeInfo]*ast.Field{}
 	t.Run(name, func(t *testing.T) {
 		for k, v := range iterateOverObjectDirect(t, fields, name, object, path) {
 			r[k] = v
@@ -121,20 +110,26 @@ func iterateOverObject(t *testing.T, fields map[string]*ast.Field, name string,
 	return r
 }
 
-func iterateOverObjectDirect(t *testing.T, fields map[string]*ast.Field, name string, object reflect.Type, path string) map[string]*ast.Field {
+func iterateOverObjectDirect(t *testing.T, fields map[string]*ast.Field, name string, object reflect.Type, path string) map[typeInfo]*ast.Field {
 	if n, simple := isSimpleType(object); simple {
-		return map[string]*ast.Field{
-			fmt.Sprintf("%s.%s:%s", path, name, n): nil,
+		return map[typeInfo]*ast.Field{
+			typeInfo{
+				path: fmt.Sprintf("%s.%s", path, name),
+				typ:  n,
+			}: nil,
 		}
 	}
 
-	r := map[string]*ast.Field{}
+	r := map[typeInfo]*ast.Field{}
 
 	switch object.Kind() {
 	case reflect.Array, reflect.Slice:
-		if n, simple := isSimpleType(object.Elem()); simple {
-			return map[string]*ast.Field{
-				fmt.Sprintf("%s.%s:[]%s", path, name, n): nil,
+		if _, simple := isSimpleType(object.Elem()); simple {
+			return map[typeInfo]*ast.Field{
+				typeInfo{
+					path: fmt.Sprintf("%s.%s", path, name),
+					typ:  "array",
+				}: nil,
 			}
 		}
 
@@ -142,9 +137,12 @@ func iterateOverObjectDirect(t *testing.T, fields map[string]*ast.Field, name st
 			r[k] = v
 		}
 	case reflect.Map:
-		if n, simple := isSimpleType(object.Elem()); simple {
-			return map[string]*ast.Field{
-				fmt.Sprintf("%s.%s:map[%s]%s", path, name, object.Key().String(), n): nil,
+		if _, simple := isSimpleType(object.Elem()); simple {
+			return map[typeInfo]*ast.Field{
+				typeInfo{
+					path: fmt.Sprintf("%s.%s", path, name),
+					typ:  "object",
+				}: nil,
 			}
 		}
 
@@ -181,7 +179,11 @@ func iterateOverObjectDirect(t *testing.T, fields map[string]*ast.Field, name st
 
 			if !f.Anonymous {
 				if t, ok := extractType(doc); ok {
-					r[fmt.Sprintf("%s.%s.%s:%s", path, name, n, t[0])] = doc
+					info := typeInfo{
+						path: fmt.Sprintf("%s.%s.%s", path, name, n),
+						typ:  t[0],
+					}
+					r[info] = doc
 					continue
 				}
 			}
@@ -252,16 +254,21 @@ func extractNotTags(n *ast.Field) ([]string, bool) {
 	return ret, len(ret) > 0
 }
 
+// isSimpleType returns the OpenAPI-compatible type name and boolean indicating if this is simple type or not
 func isSimpleType(obj reflect.Type) (string, bool) {
 	switch obj.Kind() {
-	case reflect.String,
-		reflect.Bool,
-		reflect.Int, reflect.Int32, reflect.Int64,
-		reflect.Uint, reflect.Uint16, reflect.Uint64,
-		reflect.Float32:
-		return obj.Kind().String(), true
+	case reflect.String:
+		return "string", true
+	case reflect.Bool:
+		return "boolean", true
+	case reflect.Int, reflect.Int32,
+		reflect.Uint, reflect.Uint8, reflect.Uint16:
+		return "integer", true
+	case reflect.Int64, reflect.Uint64:
+		return "integer", true
+	case reflect.Float32:
+		return "number", true
 	}
-
 	return "", false
 }
 

internal/docs_test.go

@@ -178,6 +178,7 @@ func generateDocs(t *testing.T, objects map[string]map[string]interface{}, field
 					sectionParsed := iterateOverObject(t, fields, strings.ToLower(section), reflect.TypeOf(fieldInstance), "")
 
 					defs := parseDocDefinitions(t, sectionParsed, fs)
+					defs.Sort()
 
 					renderSections[section] = defs.RenderMarkdown(t)
 				})