API

If you have an OpenAPI spec, point at it from docs.json (api.openapi) and Tangly auto-generates pages — these components are for manual reference pages or for embedding a single operation in prose.

ParamField

Documents one request parameter. The location flag (path/query/body/header) is mutually exclusive — set exactly one.

<ParamField path="userId" type="string" required>
  ID of the user. Always a UUIDv4.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Page size, max 100.
</ParamField>

<ParamField body="email" type="string" required deprecated>
  Use `contact.email` instead.
</ParamField>

ResponseField

Documents one response field. Same shape as <ParamField> minus the location flags. Pass name (or any of the location aliases — they all act as the field name).

<ResponseField name="id" type="string" required>
  Stable identifier. Never reused.
</ResponseField>

<ResponseField name="meta" type="object">
  Implementation hint — see [Meta](#meta) for the inner shape.
</ResponseField>

For nested fields, wrap a child set in <Expandable>.

RequestExample

Container for one or more request snippets, with a labeled header. Most useful with a <CodeGroup> inside so the reader can flip between cURL/JS/Python.

<RequestExample>
  <CodeGroup>
    ```bash curl
    curl https://api.example.com/v1/users/42 \
      -H "Authorization: Bearer $TOKEN"
    ```
    ```ts ts
    await fetch("https://api.example.com/v1/users/42", {
      headers: { Authorization: `Bearer ${token}` }
    })
    ```
    ```py python
    requests.get(
      "https://api.example.com/v1/users/42",
      headers={"Authorization": f"Bearer {token}"},
    )
    ```
  </CodeGroup>
</RequestExample>

ResponseExample

Same shape as <RequestExample>, but labeled “Response example.”

<ResponseExample>
  ```json
  {
    "id": "u_abc123",
    "name": "Ada Lovelace",
    "createdAt": "2026-04-29T00:00:00Z"
  }
  ```
</ResponseExample>

OpenApiEndpoint

Native Tangly OpenAPI viewer. Renders one operation with summary, parameters, responses, and a built-in try-it-out form. The spec can be a URL or a path under your project root.

<OpenApiEndpoint
  spec="/openapi.json"
  method="get"
  path="/users/{id}"
/>

The Try it panel sends a real cross-origin fetch. CORS rules apply — if your server doesn’t allow the docs origin, you’ll see a CORS error in the response panel.

OpenApiRedoc

Embeds Redoc for one operation. Standalone bundle is loaded lazily from CDN on first paint.

<OpenApiRedoc spec="/openapi.json" method="get" path="/users/{id}" />

OpenApiScalar

Embeds Scalar for one operation. Lazy-loaded ESM bundle (~50KB gzipped).

<OpenApiScalar spec="/openapi.json" method="post" path="/users" />

Same prop shape as <OpenApiRedoc>.

OpenApiStoplight

Embeds Stoplight Elements for one operation. Lazy-loaded styles + web components from CDN.

<OpenApiStoplight spec="/openapi.json" method="delete" path="/users/{id}" />

Same prop shape as <OpenApiRedoc>.

Picking a viewer

The four OpenAPI components are interchangeable in usage — pick the one that matches your aesthetic. Or skip them entirely and let docs.json api.viewer pick the global default; Tangly will then auto-generate full pages from the spec.

Source

• ParamField.astro, ResponseField.astro
• RequestExample.astro, ResponseExample.astro
• OpenApiEndpoint.astro, OpenApiRedoc.astro, OpenApiScalar.astro, OpenApiStoplight.astro