# API reference

> For the complete documentation index, see [llms.txt](https://preview.writedocs.io/llms.txt).

Turn an OpenAPI spec into an API reference - a page per endpoint, with parameters, responses, examples and a Try it playground.

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`:

```json
{
  "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](#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](https://preview.writedocs.io/docs/configuration/api-settings/).

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](https://preview.writedocs.io/docs/openapi/multi-spec-and-overrides/#your-own-page-for-an-endpoint) with a [`slug`](https://preview.writedocs.io/docs/content/frontmatter/#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 sidebar

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

- [More specs, and your own pages](https://preview.writedocs.io/docs/openapi/multi-spec-and-overrides/) - several specs in one site, and replacing a generated page with one you write.
- [Try it playground](https://preview.writedocs.io/docs/configuration/api-settings/) - how requests are sent, and the CORS proxy.
- [Parameter](https://preview.writedocs.io/docs/content/components/parameter/) and [RequestExample](https://preview.writedocs.io/docs/content/components/request-response-example/) - to document an API by hand.