Typemark Documentation

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.

Aktualisiert am 19. Nov. 20264 Min. Lesezeit

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

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

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

    {
      "navigation": {
        "tabs": [
          {
            "tab": "API Reference",
            "groups": [
              {
                "group": "Endpoints",
                "pages": [{ "source": "openapi.json" }]
              }
            ]
          }
        ]
      }
    }
  3. Publish

    Commit the change. The next build generates the pages.

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 fileOverview slug
openapi.jsonapi-reference
specs/payments.yamlpayments

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:

OperationSlug
GET /usersapi-reference/get-users
POST /usersapi-reference/post-users
GET /users/{id}api-reference/get-users-id

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 specShown as
$ref to #/components/...The referenced schema's properties
allOfThe properties of every sub-schema, merged
oneOf, anyOfThe types joined with |, like string | integer
enumThe allowed values, like "active" | "archived"
An arrayThe item type with [], like string[]

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

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:

---
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. 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 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. It links to the page you wrote for the endpoint, or else its generated page.
  • Preview the pages before you publish with typemark dev, signed in. typemark check finds a spec that won't parse: the publish would fail with its error.