Auto-generate API Reference from OpenAPI + self-healing screenshot pipeline#6
Auto-generate API Reference from OpenAPI + self-healing screenshot pipeline#6maekuss wants to merge 3 commits into
Conversation
Wire docs.json to generate the API Reference endpoint pages from a committed OpenAPI spec instead of hand-written MDX. - Add api-reference/openapi.json (OpenAPI 3.1.0) covering all 13 public endpoints: cost-estimations, scans, findings. Validated with `mintlify openapi-check`. - Point the "API Reference" tab at the spec via `openapi`, keeping the curated "Getting started" group as hand-written MDX and referencing each endpoint explicitly so group order is preserved. - Remove the now-redundant hand-written endpoint MDX (cost-estimations/*, scans/*, findings/*) to avoid duplication and drift. - Repoint internal links to the generated endpoint slugs and replace the public references to the internal /docs Swagger UI with the in-docs interactive playground. build: `mintlify openapi-check`, `broken-links`, and `validate` all pass.
Fetch the public OpenAPI spec (prod first, /docs endpoints excluded), validate with mintlify openapi-check, and open a PR only when the committed api-reference/openapi.json changed. workflow_dispatch + daily schedule, concurrency-guarded, least-privilege permissions, pinned SHAs.
Add a manifest-driven Playwright pipeline that captures product screenshots for the docs and self-heals placeholders. - automation/screenshots.json: manifest of every screenshot referenced by index.mdx and platform/** (route, auth, theme, viewport, waitFor, masks, status). Authed routes are prefixed with the org slug at runtime. - automation/screenshots/: capture harness. setup.mjs signs in via Clerk (@clerk/testing) and sets the Vercel bypass as the _vercel_jwt cookie, saving storage state; capture.mjs sets color mode deterministically, waits on explicit locators (never networkidle), masks PII, diffs, and writes only changed images, flipping fulfilled todo -> ready. - generate-placeholder.mjs + images/placeholder.png: neutral placeholder for the placeholder contract. - .github/workflows/sync-screenshots.yml: weekly + manual, PR-only, idempotent, concurrency-guarded, pinned SHAs; PR body lists unresolved todo/failed entries. - README + CONTRIBUTING: document both workflows, required secrets, the placeholder contract, and how to add a screenshot.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a293a19493
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| } | ||
|
|
||
| // Persist any todo -> ready transitions. | ||
| writeManifest(manifest); |
There was a problem hiding this comment.
Because the committed automation/screenshots.json uses compact inline objects/arrays, this unconditional JSON.stringify(..., 2) rewrites the manifest formatting even when every screenshot is unchanged and no todo entry healed. The workflow includes automation/screenshots.json in add-paths, so the next scheduled run can open a PR containing only formatting churn despite the workflow promise that PRs are opened only when an image or status changed; track whether any entry actually mutated before writing, or commit the manifest in the same normalized format.
Useful? React with 👍 / 👎.
| // Self-heal: a fulfilled "todo" becomes "ready". | ||
| if (entry.status === "todo") { | ||
| entry.status = "ready"; | ||
| result.note = (result.note ? result.note + "; " : "") + "todo fulfilled -> ready"; | ||
| } |
There was a problem hiding this comment.
When a future docs page follows the new placeholder contract (/images/placeholder.png plus a status: "todo" manifest entry), this code writes images/${entry.name}.png and flips the manifest to ready but never edits the MDX files listed in usedBy to point at that new image. In that scenario the generated PR contains the captured image and a ready manifest entry, while the published page still renders the placeholder indefinitely; the heal step should replace the placeholder reference in the affected docs file(s) or otherwise require authors to use the final image path from the start.
Useful? React with 👍 / 👎.
2 participants
Summary
Two automation changes, both PR-only, idempotent, concurrency-guarded, least-privilege, with pinned action SHAs.
Part A — API Reference auto-generated from the OpenAPI spec
api-reference/openapi.json(OpenAPI 3.1.0) covering all 13 public endpoints (cost-estimations, scans, findings;X-Api-Keyauth; basehttps://api.hacktron.ai/v1). Validated withmintlify openapi-check.docs.jsonto the spec viaopenapi, keeping Getting started as hand-written MDX and referencing each endpoint asMETHOD /pathto preserve group order.cost-estimations/*,scans/*,findings/*) so there's no duplication/drift; repointed internal links to the generated slugs./docsbasic-auth Swagger UI (replaced with the in-docs interactive playground)..github/workflows/sync-openapi.yml: daily + manual; fetches the public*/api-docs-jsonendpoint (prod first, never/docs), validates, and opens a PR only when the spec changed.Part B — Screenshot pipeline (Playwright, manifest-driven, self-healing)
automation/screenshots.json: manifest covering every screenshot referenced byindex.mdxandplatform/**(5readyplatform pages + 1todoonboarding persona screen that isn't reproducible from a seeded org).automation/screenshots/: harness —setup.mjs(Clerk programmatic sign-in via@clerk/testing+ Vercel bypass as the_vercel_jwtcookie, saved storage state) andcapture.mjs(deterministic dark color mode with verification, nevernetworkidle, explicitwaitForanchors, PII masking, pixel-diff so only changed images are written,todo → readyself-heal).images/placeholder.png: neutral generated placeholder + zero-dep generator..github/workflows/sync-screenshots.yml: weekly + manual; signs in, captures againstDOCS_APP_BASE_URL, opens a PR only when an image changed, and lists unresolvedtodo/failed entries in the PR body.Required secrets (human adds them):
CLERK_PUBLISHABLE_KEY,CLERK_SECRET_KEY,E2E_USER_EMAIL,E2E_USER_PASSWORD,E2E_ORG_SLUG,VERCEL_BYPASS_TOKEN,DOCS_APP_BASE_URL.Verification
mintlify openapi-check api-reference/openapi.json→ valid ✅mintlify broken-links→ no broken links ✅mintlify validate(strict) → build validation passed ✅node --check; manifest schema validated; placeholder is a valid 1440×900 PNG.Notes for the reviewer
The screenshot
waitFor/route/maskselectors are best-effort guesses (the app source isn't in this repo). If any are wrong, the capture run leaves the existing image untouched and lists the entry in the PR body for tuning — it can't produce a bad screenshot silently.https://claude.ai/code/session_01N1CRJkWgTr5cXqGk5tzFSg
Generated by Claude Code