WritedocsWritedocs

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:

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

Path to an OpenAPI 3.x spec (YAML or JSON), relative to the content directory (alongside writedocs.json).

pathstringrequired

The URL prefix every page generated from this spec is mounted under — e.g. /api produces pages at /api/<tag>/<operation>/.

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.

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/.

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 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.