Add an API reference

If your product has an API, the docs need a reference. The choice is usually between hand-writing every endpoint (slow, drifts) and pasting in an OpenAPI spec and letting the docs framework render it. Tangly does the second — drop the spec, get pages.

This tutorial walks through that. Five minutes if you already have a spec, fifteen if you’re writing one as you go.

Before you start

• A working Tangly project (tutorial 1 if you’re not there yet).
• An OpenAPI 3 spec — JSON or YAML. If you don’t have one, the Petstore spec works for following along.

1. Drop the spec into your project

Save the spec at openapi.json in your project root. Or anywhere else — the path you pick goes into docs.json next.

curl -o openapi.json https://petstore3.swagger.io/api/v3/openapi.json

2. Wire it up in docs.json

{
  "api": {
    "openapi": ["./openapi.json"],
    "baseUrl": "https://petstore3.swagger.io/api/v3",
    "auth":    { "method": "bearer" }
  }
}

api.openapi accepts a single spec path or an array if you have several. baseUrl overrides the spec’s servers[0].url for try-it-out — set it to your real API. auth.method controls the auth UI. bearer is the most common; see Schema → API for the full menu.

3. Choose where the endpoints live

You have two options.

Option A — auto-generated pages. Add a tab in docs.json and point its openapi field at the spec:

{
  "navigation": {
    "tabs": [
      {
        "tab": "API",
        "openapi": "./openapi.json"
      }
    ]
  }
}

Tangly walks the spec and generates one page per operation, grouped by tag. The dev server already shows them — switch to the API tab and start clicking.

Option B — hand-curated pages. Create .mdx files where you want them and reference operations from frontmatter:

---
title: List pets
description: Get every pet on the books.
openapi: GET /pet/findByStatus
---

The list endpoint returns all pets. Pagination is via the `limit` query parameter — see below.

The openapi: frontmatter field is METHOD path — the same value you’d pass to <OpenApiEndpoint>. The body of the page becomes prose around the auto-generated endpoint render.

For most API references, A is what you want. B is for cases where you need narrative context per endpoint.

4. Pick a viewer

Tangly’s built-in viewer is compact and matches the rest of your docs. If you’d rather use Scalar, ReDoc, or Stoplight, switch via:

{ "api": { "viewer": "scalar" } }

Same spec, same auto-generated pages, different render. See Schema → API → Picking a viewer.

5. Configure auth

The try-it-out form needs to know how to authenticate.

Bearer token (most APIs):

{ "api": { "auth": { "method": "bearer" } } }

API key in a header:

{ "api": { "auth": { "method": "key", "name": "X-Api-Key" } } }

Basic auth:

{ "api": { "auth": { "method": "basic" } } }

The reader fills the form once per session. Tokens stay in localStorage — never sent to your docs site itself, only to the API.

6. Multi-environment

If your API has prod, staging, and local environments, pass an array:

{
  "api": {
    "baseUrl": [
      "https://api.example.com",
      "https://staging.api.example.com",
      "http://localhost:3000"
    ]
  }
}

Try-it-out gets an environment switcher. Selection is per-visitor.

7. Validate

bunx tangly check

Spec parse errors surface here. Common issues:

• A $ref pointing to a missing component — the validator names both files.
• An operation with no summary — Tangly uses summary for the sidebar entry, falls back to operationId, and finally to METHOD path. None present means a generic label.
• A spec with circular references — Tangly resolves these but flags them.

8. Test the rendered page

Walk through 2–3 endpoints in the browser. Verify:

• The endpoint description renders (Markdown in the spec is preserved).
• Parameters show correct types and required markers.
• Try-it-out actually returns a response. CORS issues here mean the API server doesn’t allow your docs origin — fix at the API, not in Tangly.
• Response examples match what the API returns.

Where to go from here

• Schema → API — every config option in detail.
• <OpenApiEndpoint> — when to author the tag manually.
• Authoring → OpenAPI — guide-level patterns (mixing prose with auto-generated content, splitting one spec across pages).