# API Reference (OpenAPI)

A navigation group can point at an OpenAPI spec instead of listing pages by hand — Writedocs parses it, generates one page per operation (grouped by tag), and gives each one a live "Try it" playground.

## Basic setup

Add an `openapi` field to a group in place of `pages`:

```json
{
  "navigation": [
    "index",
    {
      "group": "API Reference",
      "openapi": {
        "src": "openapi.yaml",
        "path": "/api"
      }
    }
  ]
}
```

<Parameter name="src" type="string" required>
  Path to an OpenAPI 3.x spec (YAML or JSON), relative to the content directory (alongside `writedocs.json`).
</Parameter>

<Parameter name="path" type="string" required>
  The URL prefix every page generated from this spec is mounted under — e.g. `/api` produces pages at `/api/<tag>/<operation>/`.
</Parameter>

With a sample Pet API spec, this produces a "Pets" sub-group in the sidebar with pages for `GET /pets`, `POST /pets`, and `GET /pets/{petId}` — no page files to write yourself. This exact setup is live in this site's own sidebar under **Example API** — open it to see a real generated page, Try-it playground included.

<Callout type="note">
  Generated pages don't clutter your `docs/` folder — they're written to a separate build-time location and merged into the site automatically. You'll never see stray auto-generated `.mdx` files when browsing your own `docs/`.
</Callout>

## What a generated page includes

Each operation gets a page with:

- The operation's summary/description as the page title and intro.
- Every parameter (path, query, header) with type, requirement, and description.
- The request body schema, if any.
- Every documented response, with example payloads.
- A **Try it** panel — send a real request (with your own parameter values and any required auth) and see the actual response, right on the page.

## Tags become sidebar sub-groups

Operations are grouped by their OpenAPI `tags` — the first tag on each operation determines which sidebar sub-group it lands in, in first-seen order. Untagged operations are collected into a trailing "Other" group.

## Multiple specs, hand-written overrides

See [Multi-spec sites and overrides](/docs/openapi/multi-spec-and-overrides/) for mounting more than one spec in the same site, and for replacing a specific generated page with hand-written prose while keeping the rest auto-generated.