docs: add api-reference title checker script - #99
Merged
Conversation
Fetches both OpenAPI specs (wazoo-api, worlds-api) and walks every /api-reference page on docs.wazoo.dev, comparing the rendered title to the operation's declared title (x-mint.metadata.title -> summary). Reports DERIVED (no override), LOWERCASE, and MISMATCH findings and exits non-zero so it can run in CI. Expose as npm run check:api-titles. 🤖 Generated with Codebuff Co-Authored-By: Codebuff <noreply@codebuff.com>
The previous slug-overlap matching mis-attributed colliding worlds-api pages (get-worlds, post-worlds, patch-worlds, delete-worlds) to wazoo-api operations, since both specs share operationIds. Parse the authoritative (spec-url, method, path) source line from each page's Markdown variant and look up the exact operation. Also report operations present in the specs but missing from the docs sitemap. 🤖 Generated with Codebuff Co-Authored-By: Codebuff <noreply@codebuff.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
scripts/check-api-reference-titles.mjs, exposed asnpm run check:api-titles. It fetches both OpenAPI specs wired into docs.json (api.wazoo.dev/openapi.json+worlds-api.wazoo.dev/openapi.json), walks every/api-referencepage in the docs sitemap, extracts the rendered<h1>title, matches each page to its spec operation, and compares against the operation's declared title (x-mint.metadata.title→summary→ operationId-derived fallback).Findings classes
DERIVEDLOWERCASEMISMATCHUNMATCHEDExits non-zero on any finding, so it can be wired into CI (e.g. alongside
mintlify broken-links).Verified
DERIVED(worlds-api pages with no override — the exact "Get api keys" bug class from issue Docs review round 2: apply style-audit nits across all pages #18) + 4MISMATCH(stale wazoo-api collection pages whose titles no longer match the spec).LOWERCASE("Get api keys" vs declared "List API keys"), confirming the check catches the bug until docs re-deploy.npm run format:checkpasses.