From 58c33541638ed1b19b33c4c95021c2ae717b5d48 Mon Sep 17 00:00:00 2001
From: Jatin Naik <jatin.naik@snyk.io>
Date: Thu, 1 Aug 2024 17:13:48 +0100
Subject: [PATCH] feat: dry run generator if specs are changed

- to catch spec parsing faliures early
---
 .github/workflows/test-dry-run.yml | 21 ++++++++++++++++
 tools/api-docs-generator/Makefile  |  5 +++-
 tools/api-docs-generator/main.go   | 40 ++++++++++++++++++------------
 3 files changed, 49 insertions(+), 17 deletions(-)
 create mode 100644 .github/workflows/test-dry-run.yml

diff --git a/.github/workflows/test-dry-run.yml b/.github/workflows/test-dry-run.yml
new file mode 100644
index 000000000000..f1251bdac576
--- /dev/null
+++ b/.github/workflows/test-dry-run.yml
@@ -0,0 +1,21 @@
+name: Test API Docs Generation
+
+on:
+  pull_request:
+    paths:
+      - '**.yaml'
+      - '**.json'
+
+jobs:
+  test:
+    name: api-docs-generator-dry-run
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          cache-dependency-path: |
+            tools/api-docs-generator/go.sum
+      - name: test
+        working-directory: ./tools/api-docs-generator
+        run: make dry-run
diff --git a/tools/api-docs-generator/Makefile b/tools/api-docs-generator/Makefile
index 5b23f1ed73c7..ac50aac703a3 100644
--- a/tools/api-docs-generator/Makefile
+++ b/tools/api-docs-generator/Makefile
@@ -14,4 +14,7 @@ format: tidy
 	go run golang.org/x/tools/cmd/goimports -w -local=github.com/snyk/user-docs/tools/api-docs-generator .
 
 tidy:
-	go mod tidy
\ No newline at end of file
+	go mod tidy
+
+dry-run:
+	@go run . config.yml ../.. --dry-run
\ No newline at end of file
diff --git a/tools/api-docs-generator/main.go b/tools/api-docs-generator/main.go
index c404e84e365f..0c3871879fa6 100644
--- a/tools/api-docs-generator/main.go
+++ b/tools/api-docs-generator/main.go
@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"flag"
 	"log"
 	"os"
 	"path"
@@ -14,12 +15,17 @@ import (
 	"github.com/snyk/user-docs/tools/api-docs-generator/generator"
 )
 
+var dryRunFlag = flag.Bool("dry-run", false,
+	`runs the generation without updating the changelog or fetching the latest spec, `+
+		`useful for testing the validity of the current specifications`)
+
 func main() {
 	ctx, cancelCtx := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancelCtx()
-	if len(os.Args) != 3 {
+	if len(os.Args) < 3 {
 		log.Panicf("usage: api-docs <config-file> <docs-dir>")
 	}
+	flag.Parse()
 
 	cfg, err := config.Parse(os.Args[1])
 	if err != nil {
@@ -27,22 +33,24 @@ func main() {
 	}
 	docsDirectory := os.Args[2]
 
-	syncStateCfg, err := config.LoadSyncState(path.Join(docsDirectory, cfg.Changelog.SyncStateFile))
-	if err != nil {
-		log.Panic(err)
-	}
-
-	err = changelog.UpdateChangelog(ctx, cfg, syncStateCfg, docsDirectory)
-	if err != nil {
-		log.Panic(err)
-	}
-
-	// replace latest spec
-	err = fetcher.FetchSpec(ctx, cfg, docsDirectory)
-	if err != nil {
-		log.Panic(err)
+	if !*dryRunFlag {
+		var syncStateCfg config.SyncStateConfig
+		syncStateCfg, err = config.LoadSyncState(path.Join(docsDirectory, cfg.Changelog.SyncStateFile))
+		if err != nil {
+			log.Panic(err)
+		}
+
+		err = changelog.UpdateChangelog(ctx, cfg, syncStateCfg, docsDirectory)
+		if err != nil {
+			log.Panic(err)
+		}
+
+		// replace latest spec
+		err = fetcher.FetchSpec(ctx, cfg, docsDirectory)
+		if err != nil {
+			log.Panic(err)
+		}
 	}
-
 	err = generator.GenerateReferenceDocs(cfg, docsDirectory)
 	if err != nil {
 		log.Panic(err)