Make apitodoc support Ptrs and update docs (#288)

* Make apitodoc support Ptrs and update docs

* Reuse a variable

* Remove commented out code and add debug code

cmd/apitodoc/main.go

@@ -30,18 +30,17 @@ import (
 func iterate(output io.Writer, data interface{}, indent int) {
 	newIndent := indent + 1
 	dataType := reflect.ValueOf(data).Kind()
-	//dataTypeName := reflect.ValueOf(data).Type().String()
+	// DEBUG code: dataTypeName := reflect.ValueOf(data).Type().String()
 	d := reflect.ValueOf(data)
 	if dataType == reflect.Slice || dataType == reflect.Map {
 		// DEBUG code: fmt.Fprintf(output, "%s %s <-- %s \n",strings.Repeat(" ",4*indent),dataTypeName,dataType )
 		zeroElement := reflect.Zero(reflect.ValueOf(data).Type().Elem()).Interface()
-		iterate(output, zeroElement, indent+1)
+		iterate(output, zeroElement, newIndent)
 		return
 	} else if dataType == reflect.Struct {
 		// DEBUG code: fmt.Fprintf(output,"%s %s <-- %s \n",strings.Repeat(" ",4*indent),dataTypeName,dataType )
 		for i := 0; i < d.NumField(); i++ {
 			val := reflect.Indirect(reflect.ValueOf(data))
-			// fieldName := val.Type().Field(i).Name
 			fieldName := val.Type().Field(i).Tag.Get(api.TagYaml)
 			fieldName = strings.ReplaceAll(fieldName, ",omitempty", "")
 
@@ -52,7 +51,7 @@ func iterate(output io.Writer, data interface{}, indent int) {
 				enumType := api.GetEnumReflectionTypeByFieldName(fieldEnumTag)
 				zeroElement := reflect.Zero(enumType).Interface()
 				fmt.Fprintf(output, "%s %s: (enum) %s\n", strings.Repeat(" ", 4*newIndent), fieldName, fieldDocTag)
-				iterate(output, zeroElement, indent+1)
+				iterate(output, zeroElement, newIndent)
 				continue
 			}
 			if fieldDocTag != "" {
@@ -69,6 +68,13 @@ func iterate(output io.Writer, data interface{}, indent int) {
 			}
 		}
 		return
+	} else if dataType == reflect.Ptr {
+		// DEBUG code: fmt.Fprintf(output, "%s %s <-- %s \n", strings.Repeat(" ", 4*indent), dataTypeName, dataType)
+		elemType := reflect.TypeOf(data).Elem()
+		zeroElement := reflect.Zero(elemType).Interface()
+		// Since we only "converted" Ptr to Struct and the actual output is done in the next iteration, we call
+		// iterate() with the same `indent` as the current level
+		iterate(output, zeroElement, indent)
 	}
 }
 

cmd/apitodoc/main_test.go

@@ -25,11 +25,12 @@ import (
 )
 
 type DocTags struct {
-	Title string            `yaml:"title" doc:"##title"`
-	Field string            `yaml:"field" doc:"field"`
-	Slice []string          `yaml:"slice" doc:"slice"`
-	Map   map[string]string `yaml:"map" doc:"map"`
-	Sub   DocSubTags        `yaml:"sub" doc:"sub"`
+	Title  string            `yaml:"title" doc:"##title"`
+	Field  string            `yaml:"field" doc:"field"`
+	Slice  []string          `yaml:"slice" doc:"slice"`
+	Map    map[string]string `yaml:"map" doc:"map"`
+	Sub    DocSubTags        `yaml:"sub" doc:"sub"`
+	SubPtr *DocSubTags       `yaml:"subPtr" doc:"subPtr"`
 }
 
 type DocSubTags struct {
@@ -38,7 +39,7 @@ type DocSubTags struct {
 
 func Test_iterate(t *testing.T) {
 	output := new(bytes.Buffer)
-	expected := "\n##title\n<pre>\n title:\n</pre>     field: field\n     slice: slice\n     map: map\n     sub: sub\n         subField: subField\n"
+	expected := "\n##title\n<pre>\n title:\n</pre>     field: field\n     slice: slice\n     map: map\n     sub: sub\n         subField: subField\n     subPtr: subPtr\n         subField: subField\n"
 	iterate(output, DocTags{}, 0)
 	require.Equal(t, expected, output.String())
 }

docs/api.md

@@ -20,9 +20,8 @@ Following is the supported API format for prometheus encode:
          prefix: prefix added to each metric name
          expiryTime: seconds of no-flow to wait before deleting prometheus data item
          tls: TLS configuration for the prometheus endpoint
-             enable: set to true to enable tls for the prometheus endpoint
-             certFile: path to the certificate file
-             keyFile: path to the key file
+             certPath: path to the certificate file
+             keyPath: path to the key file
 </pre>
 ## Kafka encode API
 Following is the supported API format for kafka encode:
@@ -42,6 +41,10 @@ Following is the supported API format for kafka encode:
          batchBytes: limit the maximum size of a request in bytes before being sent to a partition
          batchSize: limit on how many messages will be buffered before being sent to a partition
          tls: TLS client configuration (optional)
+             insecureSkipVerify: skip client verifying the server's certificate chain and host name
+             caCertPath: path to the CA certificate
+             userCertPath: path to the user certificate
+             userKeyPath: path to the user private key
 </pre>
 ## Ingest collector API
 Following is the supported API format for the NetFlow / IPFIX collector:
@@ -71,6 +74,10 @@ Following is the supported API format for the kafka ingest:
          batchMaxLen: the number of accumulated flows before being forwarded for processing
          commitInterval: the interval (in milliseconds) at which offsets are committed to the broker.  If 0, commits will be handled synchronously.
          tls: TLS client configuration (optional)
+             insecureSkipVerify: skip client verifying the server's certificate chain and host name
+             caCertPath: path to the CA certificate
+             userCertPath: path to the user certificate
+             userKeyPath: path to the user private key
 </pre>
 ## Ingest GRPC from Network Observability eBPF Agent
 Following is the supported API format for the Network Observability eBPF ingest: