# OpenAPI reference

> Point Typemark at an OpenAPI spec and it builds an API reference, with an overview page and one page per endpoint, every time you publish.

Add an OpenAPI 3 or Swagger 2 spec to your repository, reference it in your navigation, and Typemark generates your API reference: an overview page plus one page per endpoint. The pages rebuild on every deploy, so they stay in step with the spec.

## Add your spec

<Steps>
  <Step title="Put the spec in your repository">
    Use a JSON or YAML file, such as `openapi.json` or `openapi.yaml`. Files ending in `.yaml` or `.yml` are read as YAML; everything else as JSON.
  </Step>
  <Step title="Reference it in typemark.json">
    Add an entry with `source` to a group's `pages`, using the file's path from the root of your repository:

    ```json typemark.json
    {
      "navigation": {
        "tabs": [
          {
            "tab": "API Reference",
            "groups": [
              {
                "group": "Endpoints",
                "pages": [{ "source": "openapi.json" }]
              }
            ]
          }
        ]
      }
    }
    ```
  </Step>
  <Step title="Publish">
    Commit the change. The next build generates the pages.
  </Step>
</Steps>

### From project settings

You can also do it without touching `typemark.json`. Open your project's settings and find **API Documentation**.

- Click **Upload** to add a `.json`, `.yaml`, or `.yml` file. Typemark checks that it's a spec file and commits it to the root of your repository.
- Or type the path of a spec that's already in your repository.

When you save, Typemark adds the spec to an **Endpoints** group in an **API Reference** tab, creating them if they don't exist, and rebuilds your site. Clear the field and save to remove the generated pages.

## What gets generated

### The overview page

The overview page sits in your navigation where you put the `source` entry. Its title comes from `info.title` in the spec, and it shows:

- `info.description`
- the version, from `info.version`
- the base URL, from the first entry in `servers`
- a table of every endpoint with its method, path, and summary

Its slug is the spec's file name without the extension. A file named `openapi` is the exception and gets `api-reference`.

| Spec file | Overview slug |
|-----------|---------------|
| `openapi.json` | `api-reference` |
| `specs/payments.yaml` | `payments` |

### Endpoint pages

Each `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` operation gets its own page. The title is the operation's `summary`, or the method and path when there's no summary. Each page shows:

- the method and path, with a **Deprecated** label if the operation is deprecated
- the operation's `description`
- **Parameters**: name, location, type, required, and description
- **Request Body**: the description and the top-level properties of the `application/json` schema
- **Responses**: one section per status code, with its description and the top-level properties of its `application/json` schema

Endpoint slugs live under the overview's slug and combine the method with the path:

| Operation | Slug |
|-----------|------|
| `GET /users` | `api-reference/get-users` |
| `POST /users` | `api-reference/post-users` |
| `GET /users/{id}` | `api-reference/get-users-id` |

### Sidebar

The overview page and any endpoints without a tag are listed in the group that holds your spec. Each tag gets its own group, named after the tag, right after it; an endpoint goes in the group of its first tag. Each sidebar link shows the HTTP method next to the title.

## How schemas are shown

| In the spec | Shown as |
|-------------|----------|
| `$ref` to `#/components/...` | The referenced schema's properties |
| `allOf` | The properties of every sub-schema, merged |
| `oneOf`, `anyOf` | The types joined with `\|`, like `string \| integer` |
| `enum` | The allowed values, like `"active" \| "archived"` |
| An array | The item type with `[]`, like `string[]` |

Only top-level properties are listed. Nested objects show as `object`.

<Callout type="info">
  Generated pages come from the spec alone. To add your own words to an endpoint, [write its page](#write-an-endpoints-page) instead. For guides, authentication notes, or examples, write regular pages and put them in the same tab. For endpoint docs written entirely by hand, use [API fields](https://docs.typemark.dev/components/api-fields).
</Callout>

## Write an endpoint's page

When an endpoint needs more than the spec says, such as how a flow works or which payment methods respond how, write a page for it and name the endpoint in its frontmatter with `openapi`:

```mdx reference/create-payment.mdx
---
title: Create a payment
openapi: "openapi.json POST /payment"
---

Card payments redirect the customer to their bank. Other methods answer at once.
```

The page shows everything the endpoint's generated page shows, with your text after the endpoint's description: the method and path, the description, your text, then **Parameters**, **Request Body**, and **Responses**. It's a regular page otherwise: it keeps its own address and its place in navigation, and opens in the editor like any other.

- **The spec** is a path from the root of your repository, like a `source` entry, or from your [`docs_root`](https://docs.typemark.dev/configuration/typemark-json). You can leave it out (`openapi: "POST /payment"`): Typemark then looks in the specs your navigation lists, in order. The spec doesn't have to be in your navigation.
- **The method and path** are written as they are in the spec, such as `GET /users/{id}`.
- **The title** is the endpoint's `summary` when the page has no `title`, and the description works the same way. The sidebar shows the method next to the title.
- **If Typemark can't find the endpoint**, the page shows only your text, and the deployment lists a warning saying why. [`typemark check`](https://docs.typemark.dev/automation/cli#checking-your-docs) reports it before you publish.

When a spec is also in your navigation with `{ "source": ... }`, its generated pages stay too, so you'll have both. To show only the pages you wrote, leave the spec out of navigation and write a page for each endpoint. Pages imported from Mintlify and ReadMe use the same `openapi` frontmatter.

## Tips

- Give every operation a `summary`. It becomes the page title and the sidebar label.
- Tag your operations. Tags turn a long list of endpoints into sidebar groups readers can scan.
- Keep `servers` up to date (`host`, `basePath`, and `schemes` in Swagger 2). The first URL is the base URL shown on the overview page.
- To mention an endpoint on another page, use an [endpoint line](https://docs.typemark.dev/components/api-fields#endpoint-lines). It links to the page you wrote for the endpoint, or else its generated page.
- Preview the pages before you publish with [`typemark dev`](https://docs.typemark.dev/automation/cli#api-reference-pages), signed in. `typemark check` finds a spec that won't parse: the publish would fail with its error.
