feat: Create Snaps API documentation from generated schema

[Mrtenz]

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-docs will 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

• If this PR updates or adds documentation content that changes or adds technical meaning, it has received an approval from an engineer or DevRel from the relevant team.
• If this PR updates or adds documentation content, it has received an approval from a technical writer.

External contributor checklist

• I've read the contribution guidelines.
• I've created a new issue (or assigned myself to an existing issue) describing what this PR addresses.

---

Note

Medium Risk
Introduces a new build-time doc generation step that fetches a remote schema and writes MDX files, which could break builds/CI if the schema endpoint or generation logic changes. Also rewires many internal doc links to the new per-method pages, so incorrect IDs/paths would surface as broken links or missing pages.

Overview
Snaps API reference is now generated from schema at build time. A new Docusaurus plugin (plugin-snaps-docs.ts) adds a snaps:generate CLI command that fetches the Snaps JSON-RPC schema and writes one MDX page per method under snaps/reference/snaps-api/, rendered via new SnapsAPIReference components (including markdown rendering for descriptions and structured parameter/return display).

The PR replaces the monolithic snaps/reference/snaps-api.md and wallet-api-for-snaps.md pages with a lightweight snaps/reference/snaps-api/index.md landing page and updates the Snaps sidebar to include an autogenerated “Snaps API” section. npm start/build and CI link checking now run the generation step, generated .mdx files are gitignored, and many docs are updated to link to the new per-method snaps/reference/snaps-api/<method>.mdx pages (including Wallet docs references to wallet_* methods).

^{Written by Cursor Bugbot for commit bcf6802. This will update automatically on new commits. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
metamask-docs	Ready	Preview, Comment	Mar 11, 2026 9:22am

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	react-markdown@​10.1.0

View full report

[bgravenorst]

Should there be an await?
Just asking because our existing examples often use it for snap.request

[bgravenorst]

The ToC on the right is incorrect. It's not showing Returns and Examples.

[bgravenorst]

General feedback:

• No examples for snap_closeWebSocket, snap_getPreferences, and a few others
• snap_dialog is hard to understand. The description introduces a bullet list (which is actually the parameters section). Also due to the formatting it's hard to follow what's happening in the Parameters section.
• Some examples have manifests, others don't
• snap_getLocale should this have a deprecated label?
• snap_scheduleBackgroundEvent, the “Common properties” section is confusing here because request isn’t an optional shared add-on, it’s a required top-level field in both union variants (I assume). so it would be clearer to document the parameter object once and state that exactly one of date or duration must be provided, along with the required request object.
• snap_sendWebSocketMessage Options is missing some text

[Mrtenz]

The ToC on the right is incorrect. It's not showing Returns and Examples.

@bgravenorst Do you have a good way to resolve this? It seems that Docusaurus isn't picking up the conditionally rendered headings. 😕

[Mrtenz]

@bgravenorst

• snap_dialog is hard to understand. The description introduces a bullet list (which is actually the parameters section). Also due to the formatting it's hard to follow what's happening in the Parameters section.

Agreed, I added the list description temporarily until we figure out a better way to show this. Can look into this as a follow-up if that's alright?

• Some examples have manifests, others don't

Only examples where additional permissions are needed have a manifest.

• snap_getLocale should this have a deprecated label?

Intended to remove this from the docs, but didn't push the change to the schema yet. It will be removed soon.

• snap_scheduleBackgroundEvent, the “Common properties” section is confusing here because request isn’t an optional shared add-on, it’s a required top-level field in both union variants (I assume). so it would be clearer to document the parameter object once and state that exactly one of date or duration must be provided, along with the required request object.

In this case I actually feel like it's pretty clear that request must be provided to one of the options? Do you have an example of what you were thinking?

• snap_sendWebSocketMessage Options is missing some text

This is a limitation in the schema generation script, will add some extra explanation to the message description for the time being, but can try and find a better solution in a follow-up.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[m4sterbunny]

Working fine with local build of this (drops me into new reference page) but the vercel build here is throwing me elsewhere.

[Mrtenz]

This links me to the right place in the Vercel build?

[m4sterbunny]

many links from this on are absolute instead of relative

[Mrtenz]

Not sure what you mean? These links are relative.

[m4sterbunny]

[link](absolute/link)

vs
[link](./relative/sibling-link)
or
[link](../relative/one-level-up-link)

[Mrtenz]

Markdown links are relative unless they start with / (or some protocol like https://) 😅

[bgravenorst]

Agreed, I added the list description temporarily until we figure out a better way to show this. Can look into this as a follow-up if that's alright?

Makes sense. That's fine.

In this case I actually feel like it's pretty clear that request must be provided to one of the options? Do you have an example of what you were thinking?

I had to read it a few times to understand. Or whether the request object needs to supplied inside the date or duration object. So something like this (if it was written manually)

I can't seem to figure out a way around the ToC issue

[Mrtenz]

I have hidden the TOC for now.