Merge pull request #305 from snyk/fix/improve-docs-generation

Improve docs generation

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

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"`
 }
 

tools/api-docs-generator/config/config_test.go

@@ -35,7 +35,7 @@ output:
 					{".gitbook/assets/spec.yaml", " (v1)", "hint 1"},
 					{".gitbook/assets/rest-spec.json", "", "hint 2"},
 				},
-				Output: Output{"snyk-api/reference"},
+				Output: Output{APIReferencePath: "snyk-api/reference"},
 			},
 		},
 		{

tools/api-docs-generator/generator/reference_docs.go

@@ -29,19 +29,63 @@ 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))))
 
-		err := renderReferenceDocsPage(destinationPath, label, docsBasePath, operations, cfg.CategoryContext)
+		err = renderReferenceDocsPage(destinationPath, label, docsBasePath, operations, cfg.CategoryContext)
 		if err != nil {
 			return err
 		}
 	}
 	sort.Strings(summary)
-	fmt.Printf("generated menu for summary:\n")
-	fmt.Printf("%s", strings.Join(summary, ""))
 
+	matches, err := matchCurrentSummary(cfg.Output.SummaryPath, summary)
+	if err != nil {
+		return err
+	}
+
+	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 +101,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,