API docs generator: keep developer-tools SUMMARY in sync

[VeronicaSnyk]

Problem

The API docs generator creates reference pages but never adds them to developer-tools/SUMMARY.md. It only prints a suggested menu into the automated PR's description. GitBook shows only the pages that SUMMARY.md lists, so a new page merges without appearing in the docs.snyk.io navigation. This happened with model.md in #1893, which #1896 fixes by hand.

The printed menu wasn't a reliable signal either. The check that decides whether to print it compared repo-root, unindented paths (* [X](developer-tools/snyk-api/reference/x.md)) against SUMMARY's indented, section-relative links. It never matched, so the menu appeared on every run whether or not anything had changed.

Change

• The generator now updates the SUMMARY (new generator/summary.go). It rewrites only the children of the Reference entry:
  • Adds entries for new pages in alphabetical order.
  • Removes entries for pages it no longer generates. The generator has already deleted those files, so the links would be broken.
  • Leaves existing lines and their labels untouched, so hand-edited labels such as AIBOM and Learn are kept, and a run that adds one page changes one line.
  • Stops with an error, without writing anything, if someone has nested a page under a reference entry, instead of flattening it.
• The PR body now lists only the SUMMARY entries that were added or removed, not the full menu.
• Labels that render to the same file are merged into one page. The spec has both OpenSourceSettings and OpensourceSettings, and both map to opensourcesettings.md. Previously the second render overwrote the first, and which one won depended on Go's random map order. GET /orgs/{org_id}/settings/opensource is currently missing from the published page. The merged page uses the label that sorts first, so the result is the same on every run.
• README and the workflow's PR body text describe the new behavior.

Testing

• go test ./... passes, including new tests for adding, removing, keeping labels, leaving the rest of the file alone, the missing-parent error, the nested-entry error, and merging labels.
• make dry-run against main as of the Generate API docs from spec #1893 merge:
  • SUMMARY.md gains only + * [Model](snyk-api/reference/model.md), byte-identical to Add Model API reference page to developer-tools SUMMARY #1896.
  • opensourcesettings.md regains the missing GET /orgs/{org_id}/settings/opensource endpoint.
  • A second run changes nothing.
• gofmt and go vet are clean. I couldn't run the pinned golangci-lint locally because it doesn't build on Go 1.27; CI runs it on 1.22.3.

This PR contains no regenerated docs. The OpenSourceSettings fix will arrive in the next automated sync PR.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes docs tooling and automatically edits SUMMARY.md on sync; incorrect sync logic could break GitBook nav or drop hand-maintained structure, though tests and nested-entry guards mitigate this.

Overview
The API docs generator writes the Reference children in developer-tools/SUMMARY.md during generation so new reference pages show up in GitBook navigation, instead of only printing a suggested menu that never matched the file.

syncSummary (new summary.go) rewrites only the direct children under the Reference entry: adds missing pages in sort order, drops links for deleted generated files, preserves existing labels and order for unchanged rows, and errors on nested entries without writing. Console output and the sync workflow PR body now list added/removed SUMMARY labels only.

groupPagesByFileName merges OpenAPI tags that share one output file (e.g. OpenSourceSettings / OpensourceSettings) so renders no longer overwrite each other nondeterministically. README documents the SUMMARY step.

^{Reviewed by Cursor Bugbot for commit 74d87f3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[cursor]

AI review

No style or structural issues found in the documentation content.

Verified: the documentation change updates tools/api-docs-generator/README.md to accurately describe the Reference section sync behavior in developer-tools/SUMMARY.md · numbered list structure and formatting align with existing documentation · remaining changes modify the Go generator source code and test suite.

The current head commit 74d87f3 is reviewed.

  

_{Sent by Cursor Automation: PR review for User Docs}

[cursor]

The current head commit 74d87f3 is reviewed.

  

_{Sent by Cursor Automation: PR review for User Docs}