Two New Blocks for Documenting an API: ParamField and ResponseField

The last post added Icon, a small inline primitive. This one is back to block-level content, and it's aimed squarely at one job: documenting an API.

What it does#

A request parameter or a response field has a predictable shape — a name, a type, whether it's required, maybe a default — and writing that shape out in prose every time reads worse with every parameter you add. ParamField and ResponseField give each one its own row instead.

Here's create_page, one of Dokly's own MCP tools, documented with ParamField:

The syntax:

<ParamField path="slug" type="string" required>
  URL slug, e.g. `guides/auth`. Must not already exist.
</ParamField>

The location — path, query, body, or header — is the attribute name itself, matching Mintlify's own syntax exactly: write <ParamField path="id"> for a path parameter or <ParamField query="limit"> for a query one, and ParamField reads whichever attribute you set. type defaults to "string" if you leave it off; required and default are optional.

ResponseField is the same idea for what comes back. Every MCP write Dokly's agent tools make returns a short change summary, and it looks like this documented with ResponseField:

Same shape, one fewer attribute — ResponseField only takes name, since a response field doesn't have a request location to specify.

What this doesn't do#

Mintlify's versions of these also take placeholder (pre-fills a value in an interactive API playground) and pre/post (arrays of extra labels shown before or after the name). Both are left out here. placeholder has nothing to plug into — Dokly's MDX renderer doesn't have an interactive request-building playground the way Mintlify's docs platform does. pre/post are array props, and same as Update's tags/rss, nothing in Dokly's MDX round-trip — the part that keeps your content intact when you reopen a page in the editor — handles array attributes yet. If either of those gets built, this is the component they come back to.

That brings Dokly to 20 top-level MDX components, up from 11 a couple of months ago. Still missing: Panel, Tooltips, and Tree — those are the next batches.

If you're writing an API reference and this doesn't cover how you document it, reply to this post or use the contact page — it reaches me directly.

Changelog entries#

ParamField component · Added · Documents one request parameter — path, query, body, or header — with its type, required flag, and description, as its own row on an API reference page. ResponseField component · Added · Documents one field in a response body, with its type, required flag, and description.