feat: Create Snaps API documentation from generated schema#2702
feat: Create Snaps API documentation from generated schema#2702
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
Mrtenz
force-pushed
the
mrtenz/dynamic-snaps-docs
branch
from
c507dbe to
15957dd
Compare
| import { LoadContext, Plugin } from '@docusaurus/types' | ||
|
|
||
| // TODO: Update to `latest`. | ||
| export const SNAPS_RPC_URL = 'https://metamask.github.io/snaps/schema/staging/schema.json' |
There was a problem hiding this comment.
Need to change this before merging.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| import { LoadContext, Plugin } from '@docusaurus/types' | ||
|
|
||
| // TODO: Update to `latest`. | ||
| export const SNAPS_RPC_URL = 'https://metamask.github.io/snaps/schema/staging/schema.json' |
There was a problem hiding this comment.
Staging schema URL used in production code
High Severity
SNAPS_RPC_URL points to a staging endpoint (staging/schema.json) rather than a production/latest endpoint. The accompanying TODO comment confirms this is temporary. If merged as-is, all generated Snaps API documentation will be sourced from the staging schema, which may contain incomplete, experimental, or unstable data — and the endpoint could be removed or changed without notice.
src/components/SnapsAPIReference/Parameters/Parameter/styles.module.scss
Show resolved
Hide resolved
Mrtenz
force-pushed
the
mrtenz/dynamic-snaps-docs
branch
from
1210841 to
88dd4b1
Compare
|
|
||
| {Array.isArray(props.method.examples) ? | ||
| props.method.examples.map((example, index) => ( | ||
| <Example key={index} index={index + 1} example={example} only={props.method.examples.length === 1} /> |
There was a problem hiding this comment.
Prop name mismatch prevents example titles from displaying
Medium Severity
The Examples component passes an only prop to Example, but the Example component reads props.showTitle to decide whether to render the <h3> title. Since showTitle is never provided, example titles are never rendered. The only prop is unused.
Additional Locations (1)
| ` | ||
|
|
||
| await writeFile(filePath, content) | ||
| } |
There was a problem hiding this comment.
Missing cleanup of stale generated docs before regeneration
Medium Severity
generateSnapsDocs writes new .mdx files into snaps/reference/snaps-api/ but never clears existing files from previous runs. If a method is renamed or removed from the schema between runs, the old .mdx file persists on disk. Docusaurus then picks up both stale and current files, resulting in phantom documentation pages for methods that no longer exist in the schema. Clearing the output directory before writing would prevent this.
src/components/SnapsAPIReference/Parameters/Parameter/UnionParameter/index.tsx
Show resolved
Hide resolved
src/components/SnapsAPIReference/Parameters/Parameter/styles.module.scss
Show resolved
Hide resolved
| </TabItem> | ||
| ))} | ||
| </Tabs> | ||
| : <CodeBlock language={props.example.examples[0].language}>{props.example.examples[0].content}</CodeBlock> |
There was a problem hiding this comment.
Accessing index zero of potentially empty array crashes
Low Severity
If an example group from the schema has an empty examples array (length 0), the condition on line 7 (examples.length > 1) is false, causing the else branch on line 15 to evaluate props.example.examples[0].language. Since [0] on an empty array is undefined, this throws a TypeError and crashes the page. No guard ensures the inner examples array is non-empty before accessing its first element.
1 participant
Description
This adds a Docusaurus plugin for dynamically generating Snaps API documentation from a schema file. The schema file will be generated automatically based on the implementations in
MetaMask/snaps. This allows for easier maintenance of the documentation, as some methods have become quite outdated currently.The plugin works by fetching the schema file, and writing a new MDX file to disk for each JSON-RPC method. I've considered a similar approach to the Wallet API documentation, but it had several drawbacks, like needing to hack the sidebar to show the dynamic items. By generating the MDX files before running Docusaurus,
@docusaurus/plugin-content-docswill just pick it up as any other documentation page.Related to: https://consensyssoftware.atlassian.net/browse/WPC-347 and https://consensyssoftware.atlassian.net/browse/WPC-442.
Preview
Checklist
External contributor checklist
Note
Medium Risk
Introduces a build-time fetch-and-generate step for docs pages (network dependency and generated content shape), which can break builds/link checks if the schema or generation output changes unexpectedly.
Overview
Adds a custom Docusaurus plugin (
plugin-snaps-docs) andsnaps:generateCLI command that fetches the Snaps JSON-RPC schema and generates per-methodsnaps/reference/snaps-api/*.mdxpages rendered via a newSnapsAPIReferencecomponent (including markdown descriptions, parameter/return type rendering, examples, and tags).Reworks Snaps docs navigation and links to point at the new generated reference structure (new
snaps/reference/snaps-api/index.md, updatedsnaps-sidebar.js, and widespread link updates), and removes the old monolithicsnaps/reference/snaps-api.mdpage.Integrates generation into local and CI workflows by running
docusaurus snaps:generateduringnpm start/buildand before link checking, addsreact-markdowndependency, and ignores generated MDX outputs in.gitignore.Written by Cursor Bugbot for commit 92e71cd. This will update automatically on new commits. Configure here.