feat: dry run generator if specs are changed

- to catch spec parsing faliures early

.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

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
+	go mod tidy
+
+dry-run:
+	@go run . config.yml ../.. --dry-run

tools/api-docs-generator/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"flag"
 	"log"
 	"os"
 	"path"
@@ -14,35 +15,42 @@ 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 {
 		log.Panic(err)
 	}
 	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)