From fb218d4733056264e28909b32685f391ff4ef580 Mon Sep 17 00:00:00 2001
From: Jatin Naik <jatin.naik@snyk.io>
Date: Fri, 31 May 2024 14:39:12 +0100
Subject: [PATCH] Improve docs generation - Filter out openapi category -
 Delete files before generation, making category renames possible - Print the
 menu only if the summary has changed

---
 tools/api-docs-generator/config.yml           |  1 +
 tools/api-docs-generator/config/config.go     |  1 +
 .../generator/reference_docs.go               | 47 ++++++++++++++++++-
 3 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/tools/api-docs-generator/config.yml b/tools/api-docs-generator/config.yml
index 1dcbe9a97be8..e4c45924cab9 100644
--- a/tools/api-docs-generator/config.yml
+++ b/tools/api-docs-generator/config.yml
@@ -12,4 +12,5 @@ categoryContext:
   hint: |
     **Note:** When you import or update Projects, changes will be reflected in the endpoint results after a one-hour delay.
 output:
+  summaryPath: docs/SUMMARY.md
   apiReferencePath: docs/snyk-api/reference
\ No newline at end of file
diff --git a/tools/api-docs-generator/config/config.go b/tools/api-docs-generator/config/config.go
index b90e346deeb7..9ed8bbeecb6c 100644
--- a/tools/api-docs-generator/config/config.go
+++ b/tools/api-docs-generator/config/config.go
@@ -18,6 +18,7 @@ type Spec struct {
 }
 
 type Output struct {
+	SummaryPath      string `yaml:"summaryPath"`
 	APIReferencePath string `yaml:"apiReferencePath"`
 }
 
diff --git a/tools/api-docs-generator/generator/reference_docs.go b/tools/api-docs-generator/generator/reference_docs.go
index 051d22f690ca..dd82ed54ca70 100644
--- a/tools/api-docs-generator/generator/reference_docs.go
+++ b/tools/api-docs-generator/generator/reference_docs.go
@@ -29,6 +29,11 @@ func GenerateReferenceDocs(cfg *config.Config, docsBasePath string) error {
 	}
 
 	summary := make([]string, len(aggregatedDocs))
+	err = clearDir(path.Join(docsBasePath, cfg.Output.APIReferencePath))
+	if err != nil {
+		return err
+	}
+
 	for label, operations := range aggregatedDocs {
 		destinationPath := path.Join(docsBasePath, cfg.Output.APIReferencePath, labelToFileName(label))
 		summary = append(summary, fmt.Sprintf("* [%s](%s)\n", label, path.Join(cfg.Output.APIReferencePath, labelToFileName(label))))
@@ -39,9 +44,44 @@ func GenerateReferenceDocs(cfg *config.Config, docsBasePath string) error {
 		}
 	}
 	sort.Strings(summary)
-	fmt.Printf("generated menu for summary:\n")
-	fmt.Printf("%s", strings.Join(summary, ""))
 
+	matches, err := matchCurrentSummary(cfg.Output.SummaryPath, summary)
+	if !matches {
+		fmt.Printf("generated menu for summary:\n")
+		fmt.Printf("%s", strings.Join(summary, ""))
+	}
+
+	return nil
+}
+
+func matchCurrentSummary(summaryPath string, summary []string) (bool, error) {
+	contents, err := os.ReadFile(summaryPath)
+	if err != nil {
+		return false, fmt.Errorf("failed to read summary file: %w", err)
+	}
+	currentSummary := string(contents)
+	for _, menuItem := range summary {
+		if !strings.Contains(currentSummary, menuItem) {
+			return false, nil
+		}
+	}
+	return true, nil
+}
+
+func clearDir(dirName string) error {
+	dir, err := os.ReadDir(dirName)
+	if err != nil {
+		return err
+	}
+	for _, child := range dir {
+		if strings.HasPrefix(child.Name(), "README") {
+			continue
+		}
+		err = os.RemoveAll(path.Join(dirName, child.Name()))
+		if err != nil {
+			return err
+		}
+	}
 	return nil
 }
 
@@ -57,6 +97,9 @@ func aggregateSpecs(cfg *config.Config, docsBasePath string) (map[string][]opera
 		for pathURL, pathItem := range doc.Paths.Map() {
 			for method, operation := range pathItem.Operations() {
 				for _, tag := range operation.Tags {
+					if tag == "OpenAPI" {
+						continue
+					}
 					tag += spec.Suffix
 					aggregatedDocs[tag] = append(aggregatedDocs[tag], operationPath{
 						operation: operation,