docs: generate a frontmatter description for API reference pages

[VeronicaSnyk]

Group C item 11 of the September 2026 AI-readiness audit.

The question this answers

The audit asked whether the ~60 pages under developer-tools/snyk-api/reference/ are generated by a pipeline, because that determines the whole approach. They are: tools/api-docs-generator/config.yml sets apiReferencePath: developer-tools/snyk-api/reference, and the sync workflow runs hourly.

That is why PR #1757, which added descriptions to 68 pages, deliberately skipped these 59. A hand-edited description would be erased on the next sync. The fix belongs in the generator.

The change

renderReferenceDocsPage now emits a frontmatter description before the H1. GitBook reads the page description from frontmatter, and it must be the first thing in the file.

The text is derived from the category label rather than written per page, so all 59 get one and any future endpoint group is covered automatically.

---
description: Snyk API reference for the Apps endpoints, including request parameters and response schemas
---

# Apps

Why it matters

A page with no description gives search results and AI assistants nothing to quote. The API reference is 59 of the 146 pages the audit found missing one — the single largest block, and the only one that could not be fixed by editing Markdown.

Testing

Two tests are added: one asserting the rendered page starts with a frontmatter description and that it precedes the H1, one covering the description helper directly.

These were not run locally. Go is not installed in the authoring environment, so I verified the change by inspection only. test-generator.yml builds and runs the suite on this PR — please treat CI as the real check. If the build fails, the likely cause is the strings import I added to the test file.

After merge

The next scheduled run of sync-api-docs regenerates the 59 pages with descriptions. No manual step is needed, but it is worth confirming on the first auto-generated PR that the frontmatter renders as expected in the GitBook preview.

---

Note

Low Risk
Docs-generator output-only change with unit tests; regenerated reference pages pick up descriptions on the next sync.

Overview
The API reference doc generator now prepends GitBook frontmatter with an auto-generated description (before the H1) on every renderReferenceDocsPage output, via new helper referencePageDescription that formats text from the category label.

Tests assert the description block is first in the file and stays single-line; existing render tests were adjusted for a simpler temp-file helper.

^{Reviewed by Cursor Bugbot for commit 6b77146. 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.

Verified: tools/api-docs-generator successfully generates valid YAML frontmatter description blocks on reference documentation pages · test coverage in reference_docs_test.go confirms description positioning before the top-level H1 heading · test suite passes with make test.

The current head commit 6b77146 is reviewed.

  

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