API reference

Point a navigation group at an OpenAPI spec, and Writedocs writes the API reference: a page for every endpoint, grouped by tag, with its parameters, request body, responses, code examples and a Try it playground. There are no page files to write or keep up to date - change the spec, and the pages follow.

Set it up

Put the spec in your project, and give a group openapi in place of pages:

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

src string required

The spec’s path from the project folder: an OpenAPI 3.0 or 3.1 file, in YAML or JSON.

path string required

The address the pages go under - see Page addresses. Each OpenAPI group needs its own.

This site’s Example API group, in this tab’s sidebar, is set up exactly like this - its pages are generated from a sample spec.

The spec must be a file in the project - a URL isn’t fetched. writedocs validate checks every spec in the navigation: a spec that’s missing or doesn’t parse is an error, and one that parses but isn’t valid OpenAPI is a warning.

What each page shows

The endpoint - its method and path, title (the operation’s summary) and description. Descriptions are Markdown, as OpenAPI specifies.
Authorization - the security schemes the endpoint accepts.
Parameters - path, query and header parameters, with their type, whether they’re required, their default and description.
Request body - every field, with nested objects that open and close.
Responses - each status code, with its fields and an example.
Code examples - the request in several languages, ready to copy, beside the page.
Try it - a playground that sends a real request to your API - see Try it playground.

The page also has the Copy page menu, and its Markdown copy, llms-full.txt and the MCP server include the endpoint written out in full.

Page addresses

An endpoint’s page is served at the group’s path, then the endpoint’s first tag, then its method and path:

Endpoint	Tags	Address, with `path: "/api"`
`POST /customers`	`Customers`	`/api/customers/post-customers/`
`GET /customers/{id}`	`Customers`, `Admin`	`/api/customers/get-customers-id/`
`GET /health`	none	`/api/get-health/`

To choose an endpoint’s address yourself, give it a page of its own with a slug.

In search results and link previews, the page’s description is the endpoint’s description as plain text, cut to about 160 characters - or, when it has none, its summary and request: List all customers - GET /customers.

Limits

allOf schemas are merged into one. For oneOf and anyOf, the page shows the first option only - describe the others in its description.

The group lists the endpoints under one group per tag, in the order the tags first appear in the spec. An endpoint takes its first tag; endpoints with no tag go in a group called Other. Each endpoint shows its method next to its name.

Writing a good spec

The pages are only as good as the spec. What helps most:

A summary for every operation - it’s the page’s title and its name in the sidebar.
A description for operations, parameters and fields.
example or examples values, for the response examples and the playground’s starting values.
tags, to group the endpoints.
servers, for the address the playground sends requests to.

More specs, and your own pages - several specs in one site, and replacing a generated page with one you write.
Try it playground - how requests are sent, and the CORS proxy.
Parameter and RequestExample - to document an API by hand.