# API Reference (Moonarc)

An API reference in one section: a sidebar of groups and their operations; for each operation its method and path, what it does, its path, query and header parameters, the fields of its body (nested fields under a disclosure, as deep as they go) and its responses; and beside it, sticky on a wide screen, the request in every language with a copy button and the response examples by status. The language picked once switches every sample on the page through radios and :has(), with no script; a small script remembers it for the next page. A type with more to say (a format, a range) carries it in a Tooltip, and the sidebar marks the operation in view where the browser has scroll-target-group. It takes operations already shaped, the way a template turns an OpenAPI document into them at build.

- Pro block. Install: `npx shadcn@latest add @moonarc-pro/api-reference` (license key required)
- Tier B · category section · trigger click
- Readout: `<ApiReference languages={[…]} groups={[{ title, operations }]} />`
- Browser support: newly (Chrome 131 · Firefox 143 · Safari 18.4); elsewhere: without ::details-content the sidebar on a wide screen opens with a click; without :has() the first language shows
- Measured cost: 404 B raw JS · 285 B gzip · + CopyButton + runtime (with dependencies 2.9 kB raw; CSS 28.6 kB raw)
- Page: https://moonarc.dev/components/api-reference/

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `groups` | `{ id; title; description?; operations }[]` | none | The groups, each with its operations: { id, method, path, summary, description?, deprecated?, params?, body?, samples, responses }. params are fields with in (path, query, header); a field is { name, type, required?, description?, detail?, enum?, default?, children? }; samples are { label, code, lang? }, one per language; responses are { status, description?, example? }. Descriptions are paragraphs split by a blank line, with `code` in backticks. |
| `languages` | `{ label: string; lang?: string }[]` | none | One to six languages every sample comes in, in this order; the first is picked at first. lang is the Shiki language id. An operation without a sample for one of them stops the build naming it. |
| `base` | `string` | none | The base URL, printed in the introduction. |
| `title` | `string` | none | The page's heading. |
| `intro` | `string` | none | Paragraphs under the heading, split by a blank line; `code` in backticks. |
| `id` | `string` | `'ma-apiref'` | Prefix of the radio names and the localStorage key the language is kept under; unique on the page. |
| `words` | `Partial<Words>` | none | Every word the reference prints around your content: Language, Endpoints, the parameter headings, Body, Responses, required and optional, Deprecated, One of, Default, Fields, Request. |
| `level` | `1 | 2` | `1` | Heading level of the title; groups are one below and operations two below. |

## Usage

```astro
---
import ApiReference from '@/components/moonarc/pro/ApiReference.astro';
import { reference } from '../lib/openapi';   // your OpenAPI document, shaped at build
---
<ApiReference
  title="API reference"
  intro="Every request takes your key as a bearer token."
  base="https://api.example.com/v1"
  languages={[{ label: 'cURL', lang: 'sh' }, { label: 'JavaScript', lang: 'js' }, { label: 'Python', lang: 'python' }]}
  groups={reference.groups}
/>
```

## Reduced motion

Nothing moves but the language picker's colour, which changes at once.

## With ClientRouter

The remembering script is bound through the shared runtime and reads the language again on every page.

## Craft

- One language for the whole page: a reader who works in Python reads Python in every sample, and the choice follows them to the next page. The radios do the switching; the script only remembers.
- The request panel is dark on every page, as a terminal is, and --ma-dark is 1 inside it so Shiki's dark colours are the ones painted, each moved at build until it reads at 4.5 : 1. The responses are CodeTabs, re-tokened to the same panel.
- Nested fields wait under a disclosure with their count, so a large object does not push the next operation off the screen.
- The samples stick beside the docs on a wide box and follow them on a narrow one: a reader always has the request in view while reading its parameters.
- Every operation must have a sample in every language, checked at build, so switching never lands on an empty panel.
- A path's variables ({id}) are set in the emphasis colour, so the part to replace is the part that stands out.

## Replaces

- Redoc
- Swagger UI
- Scalar API reference
- Protocol (Tailwind Plus) API reference pages

## Source

Pro block. The source is served by the license-gated registry: `npx shadcn@latest add @moonarc-pro/api-reference` with a key in components.json (https://moonarc.dev/account/). Everything it composes is free: code-tabs, copy-button.